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 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 CMAKE_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)