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

## 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.