From 905d461431b0f2803fbd7d87ebd16e41748d9155 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Tue, 15 Apr 2025 13:30:38 +0200 Subject: Find_SDL*: Update documentation This updates the following modules: - FindSDL - FindSDL_gfx - FindSDL_image - FindSDL_mixer - FindSDL_net - FindSDL_sound - FindSDL_ttf Changes: - Synced modules documentation. - Added examples sections. - Used the ``_FOUND`` variables. The uppercased ``_FOUND`` variables are also set to the same value as of CMake 3.3. - Added notes regarding the CMake package configuration files provided by upstream distributions with separate imported targets. - Find modules index sorted alphabetically for FindSDL* modules. --- Help/manual/cmake-modules.7.rst | 2 +- Modules/FindSDL.cmake | 182 +++++++++++++++++++++++++++------------- Modules/FindSDL_gfx.cmake | 71 +++++++++++++--- Modules/FindSDL_image.cmake | 105 +++++++++++++++++++---- Modules/FindSDL_mixer.cmake | 97 +++++++++++++++++---- Modules/FindSDL_net.cmake | 96 +++++++++++++++++---- Modules/FindSDL_sound.cmake | 157 +++++++++++++++++++++++++--------- Modules/FindSDL_ttf.cmake | 102 +++++++++++++++++++--- 8 files changed, 645 insertions(+), 167 deletions(-) diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 7542e93..d9b9f2e 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/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 diff --git a/Modules/FindSDL.cmake b/Modules/FindSDL.cmake index 0e85990..a720dcc 100644 --- a/Modules/FindSDL.cmake +++ b/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[_]`` - 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 . 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) diff --git a/Modules/FindSDL_gfx.cmake b/Modules/FindSDL_gfx.cmake index fb066c9..c7f489e 100644 --- a/Modules/FindSDL_gfx.cmake +++ b/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) diff --git a/Modules/FindSDL_image.cmake b/Modules/FindSDL_image.cmake index 995baaa..5835532 100644 --- a/Modules/FindSDL_image.cmake +++ b/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) diff --git a/Modules/FindSDL_mixer.cmake b/Modules/FindSDL_mixer.cmake index 5219f84..a9bafbc 100644 --- a/Modules/FindSDL_mixer.cmake +++ b/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) diff --git a/Modules/FindSDL_net.cmake b/Modules/FindSDL_net.cmake index a8189fb..c5ba976 100644 --- a/Modules/FindSDL_net.cmake +++ b/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) diff --git a/Modules/FindSDL_sound.cmake b/Modules/FindSDL_sound.cmake index 30a89aa..954303f 100644 --- a/Modules/FindSDL_sound.cmake +++ b/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) `. -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. #]=======================================================================] diff --git a/Modules/FindSDL_ttf.cmake b/Modules/FindSDL_ttf.cmake index 080705f..2569588 100644 --- a/Modules/FindSDL_ttf.cmake +++ b/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) -- cgit v0.12