FindSDL

查找 SDL (Simple DirectMedia Layer) 库

find_package(SDL [<version>] [...])

SDL 是一个跨平台的库，用于开发多媒体软件，例如游戏和模拟器。

注意

此模块专门针对 SDL 版本 1。从版本 2 开始，SDL 在使用 CMake 构建时会提供一个 CMake 包配置文件，应该使用 find_package(SDL2) 来查找。类似地，SDL 版本 3 可以使用 find_package(SDL3) 来查找。这些较新版本提供了单独的 Imported Targets，用于封装使用需求。有关更多信息，请参阅官方 SDL 文档。

请注意，在最近的 SDL 1 版本中，SDL 头文件的包含路径已从 SDL/SDL.h 更改为 SDL.h。此更改符合 SDL 使用 #include "SDL.h" 以实现可移植性的约定，因为并非所有系统都会将头文件安装在 SDL/ 子目录中（例如，FreeBSD）。

当目标为 macOS 并使用 SDL 框架时，请务必在项目中同时包含 SDLmain.h 和 SDLmain.m。对于其他平台，SDLmain 库通常使用 -lSDLmain 进行链接，本模块将尝试自动定位。此外，对于 macOS，本模块将在需要时添加 -framework Cocoa 标志。

导入的目标

此模块提供以下 导入目标

SDL::SDL

3.19 版本新增。

封装 SDL 库使用需求的 Target，如果在找到 SDL 时可用。

结果变量

此模块定义了以下变量

SDL_FOUND

布尔值，指示是否找到（请求版本的）SDL。

SDL_VERSION

3.19 版本新增。

包含找到的 SDL 版本的可读字符串。

SDL_VERSION_MAJOR

3.19 版本新增。

找到的 SDL 的主版本号。

SDL_VERSION_MINOR

3.19 版本新增。

找到的 SDL 的次版本号。

SDL_VERSION_PATCH

3.19 版本新增。

找到的 SDL 的补丁版本号。

SDL_INCLUDE_DIRS

3.19 版本新增。

使用 SDL 所需的包含目录。

SDL_LIBRARIES

3.19 版本新增。

链接使用 SDL 所需的库。

缓存变量

这些变量可选择性地设置为帮助此模块找到正确的文件

SDL_INCLUDE_DIR

包含 SDL.h 头文件的目录。

SDL_LIBRARY

一个包含 SDL 库路径以及链接使用 SDL 所需库的列表。

提示

此模块接受以下变量

SDL_BUILDING_LIBRARY

当设置为布尔值 true 时，将从链接中排除 SDL_main 库，因为它在构建 SDL 库本身时不是必需的（只有应用程序需要 main() 函数）。如果未设置，此模块将假定正在构建应用程序，并尝试在返回的 SDL_LIBRARY 变量中查找并包含适当的 SDL_main 链接标志。

SDLDIR

环境变量，可用于帮助定位安装在自定义位置的 SDL 库。它应指向配置、构建和安装 SDL 库时使用的安装目标：./configure --prefix=$SDLDIR。

在 macOS 上，设置此变量将优先选择 Framework 版本（如果找到）。在这种情况下，需要手动更改 SDL_LIBRARY 的缓存值以覆盖此选择，或设置 CMAKE_INCLUDE_PATH 变量来修改搜索路径。

故障排除

如果 SDL 库未自动找到，SDL_LIBRARY_TEMP 变量可能为空，而 SDL_LIBRARY 将不会被设置。这通常意味着 CMake 无法定位 SDL 库（例如 SDL.dll、libSDL.so、SDL.framework 等）。要解决此问题，请手动设置 SDL_LIBRARY_TEMP 为正确的路径并重新配置项目。类似地，如果 SDLMAIN_LIBRARY 未设置，也可能需要手动指定。这些变量用于构建最终的 SDL_LIBRARY 值。如果它们未设置，SDL_LIBRARY 将保持未定义。

已弃用变量

以下变量提供用于向后兼容性

SDL_VERSION_STRING

已弃用，版本 3.19 起： 已被具有相同值的 SDL_VERSION 取代。

如果找到 SDL，包含其版本的可读字符串。

示例

查找 SDL 库并将其链接到项目 Target

find_package(SDL)
target_link_libraries(project_target PRIVATE SDL::SDL)

在使用 SDL 版本 2 时，上游包直接提供了 SDL2::SDL2 导入 Target。可以在不使用此模块的情况下在项目中直接使用它

find_package(SDL2)
target_link_libraries(project_target PRIVATE SDL2::SDL2)

类似地，对于 SDL 版本 3

find_package(SDL3)
target_link_libraries(project_target PRIVATE SDL3::SDL3)

另请参阅