FindSDL

Finds the SDL (Simple DirectMedia Layer) library. SDL is a cross-platform library for developing multimedia software, such as games and emulators.

備註

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

在 3.19 版被加入.

Target encapsulating the SDL library usage requirements, available if SDL is found.

結果變數

This module defines the following variables:

SDL_FOUND

Boolean indicating whether the (requested version of) SDL is found.

SDL_VERSION

在 3.19 版被加入.

The human-readable string containing the version of SDL found.

SDL_VERSION_MAJOR

在 3.19 版被加入.

The major version of SDL found.

SDL_VERSION_MINOR

在 3.19 版被加入.

The minor version of SDL found.

SDL_VERSION_PATCH

在 3.19 版被加入.

The patch version of SDL found.

SDL_INCLUDE_DIRS

在 3.19 版被加入.

使用 SDL 所需的引入目錄。

SDL_LIBRARIES

在 3.19 版被加入.

使用 SDL 所需連結的程式庫。

快取變數

These variables may optionally be set to help this module find the correct files:

SDL_INCLUDE_DIR

包含 SDL.h 標頭檔的目錄。

SDL_LIBRARY

A list of libraries containing the path to the SDL library and libraries needed to link against to use SDL.

Hints

該模組接受以下變數：

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.

疑難排解

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.

已棄用的變數

These variables are obsolete and provided for backwards compatibility:

SDL_VERSION_STRING

在 3.19 版之後被棄用: Superseded by the SDL_VERSION with the same value.

The human-readable string containing the version of SDL if found.

範例

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)

另請參見