FindSDL¶
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
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¶
This module provides the following Imported Targets:
SDL::SDL
Added in version 3.19.
Target encapsulating the SDL library usage requirements, available if SDL is found.
Result Variables¶
This module defines the following variables:
SDL_FOUND
Boolean indicating whether the (requested version of) SDL is found.
SDL_VERSION
Added in version 3.19.
The human-readable string containing the version of SDL found.
SDL_VERSION_MAJOR
Added in version 3.19.
The major version of SDL found.
SDL_VERSION_MINOR
Added in version 3.19.
The minor version of SDL found.
SDL_VERSION_PATCH
Added in version 3.19.
The patch version of SDL found.
SDL_INCLUDE_DIRS
Added in version 3.19.
Include directories needed to use SDL.
SDL_LIBRARIES
Added in version 3.19.
Libraries needed to link against to use SDL.
Cache Variables¶
These variables may optionally be set to help this module find the correct files:
SDL_INCLUDE_DIR
The directory containing the
SDL.h
header file.SDL_LIBRARY
A list of libraries containing the path to the SDL library and libraries needed to link against to use SDL.
Hints¶
This module accepts the following variables:
SDL_BUILDING_LIBRARY
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 needmain()
function). If not set, this module assumes an application is being built and attempts to locate and include the appropriateSDL_main
link flags in the returnedSDL_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 theCMAKE_INCLUDE_PATH
variable to modify the search paths.
Troubleshooting¶
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 Variables¶
These variables are obsolete and provided for backwards compatibility:
SDL_VERSION_STRING
Deprecated since version 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:
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:
find_package(SDL2)
target_link_libraries(project_target PRIVATE SDL2::SDL2)
Similarly, for SDL version 3:
find_package(SDL3)
target_link_libraries(project_target PRIVATE SDL3::SDL3)
See Also¶
The
FindSDL_gfx
module to find the SDL_gfx library.The
FindSDL_image
module to find the SDL_image library.The
FindSDL_mixer
module to find the SDL_mixer library.The
FindSDL_net
module to find the SDL_net library.The
FindSDL_sound
module to find the SDL_sound library.The
FindSDL_ttf
module to find the SDL_ttf library.