CMake无法找到SDL2TTF包问题求助（附配置文件）

算力阿峰

2026-6-20

CMake无法定位SDL2TTF库的问题解决

问题现象

CMake执行时抛出如下错误：

CMake Error at C:/Program Files/JetBrains/CLion 2023.3.4/bin/cmake/win/x64/share/cmake-3.27/Modules/FindPackageHandleStandardArgs.cmake:230 (message):
  Could NOT find SDL2TTF (missing: SDL2TTF_LIBRARY SDL2TTF_INCLUDE_DIR)
Call Stack (most recent call first):
  C:/Program Files/JetBrains/CLion 2023.3.4/bin/cmake/win/x64/share/cmake-3.27/Modules/FindPackageHandleStandardArgs.cmake:600 (_FPHSA_FAILURE_MESSAGE)
  cmake_modules/FindSDL2TTF.cmake:163 (FIND_PACKAGE_HANDLE_STANDARD_ARGS)
  CMakeLists.txt:17 (find_package)

SDL2与SDL2_image配置正常，仅SDL2TTF无法被识别，已完成库文件下载、自定义Find模块创建及CMakeLists.txt更新。

用户配置文件

CMakeLists.txt

cmake_minimum_required(VERSION 3.27)
project(Projects)

set(CMAKE_CXX_STANDARD 23)

set(CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake_modules/ ${CMAKE_MODULE_PATH})
set(SDL2_PATH "C:/libs/SDL2-2.30.1/x86_64-w64-mingw32")
set(SDL2_IMAGE_PATH "C:/libs/SDL2_image-2.8.2/x86_64-w64-mingw32")
set(SDL2_TTF_PATH "C:/libs/SDL2_ttf-2.22.0/x86_64-w64-mingw32")

configure_file(images/Tic-tac-toe.bmp ${CMAKE_BINARY_DIR}/images/Tic-Tac-Toe.bmp COPYONLY)
configure_file(images/circle-1.png.png ${CMAKE_BINARY_DIR}/images/circle-1.png.png COPYONLY)
configure_file(images/X.png ${CMAKE_BINARY_DIR}/images/X.png COPYONLY)

find_package(SDL2 REQUIRED)
find_package(SDL2_image REQUIRED)
find_package(SDL2TTF REQUIRED)
include_directories(${SDL2_INCLUDE_DIR} ${SDL2_IMAGE_INCLUDE_DIRS} ${SDL2TTF_INCLUDE_DIRS})
add_executable(Projects main.cpp
        TicTacToe.h
        TicTacToe.cpp
        O_Symol.h
        X_Symbol.h
        O_Symol.cpp
        X_Symbol.cpp
)

target_link_libraries(${PROJECT_NAME} ${SDL2_LIBRARY} ${SDL2_IMAGE_LIBRARIES} ${SDL2TTF_LIBRARIES})

FindSDL2TTF.cmake

# Locate SDL2 library
# This module defines
# SDL2_LIBRARY, the name of the library to link against
# SDL2_FOUND, if false, do not try to link to SDL2
# SDL2_INCLUDE_DIR, where to find SDL.h
#
# This module responds to the the flag:
# SDL2_BUILDING_LIBRARY
# If this is defined, then no SDL2main will be linked in because
# only applications need main().
# Otherwise, it is assumed you are building an application and this
# module will attempt to locate and set the the proper link flags
# as part of the returned SDL2_LIBRARY variable.
#
# Don't forget to include SDLmain.h and SDLmain.m your project for the
# OS X framework based version. (Other versions link to -lSDL2main which
# this module will try to find on your behalf.) Also for OS X, this
# module will automatically add the -framework Cocoa on your behalf.
#
#
# Additional Note: If you see an empty SDL2_LIBRARY_TEMP in your configuration
# and no SDL2_LIBRARY, it means CMake did not find your SDL2 library
# (SDL2.dll, libsdl2.so, SDL2.framework, etc).
# Set SDL2_LIBRARY_TEMP to point to your SDL2 library, and configure again.
# Similarly, if you see an empty SDL2MAIN_LIBRARY, you should set this value
# as appropriate. These values are used to generate the final SDL2_LIBRARY
# variable, but when these values are unset, SDL2_LIBRARY does not get created.
#
#
# $SDL2DIR is an environment variable that would
# correspond to the ./configure --prefix=$SDL2DIR
# used in building SDL2.
# l.e.galup  9-20-02
#
# Modified by Eric Wing.
# Added code to assist with automated building by using environmental variables
# and providing a more controlled/consistent search behavior.
# Added new modifications to recognize OS X frameworks and
# additional Unix paths (FreeBSD, etc).
# Also corrected the header search path to follow "proper" SDL guidelines.
# Added a search for SDL2main which is needed by some platforms.
# Added a search for threads which is needed by some platforms.
# Added needed compile switches for MinGW.
#
# On OSX, this will prefer the Framework version (if found) over others.
# People will have to manually change the cache values of
# SDL2_LIBRARY to override this selection or set the CMake environment
# CMAKE_INCLUDE_PATH to modify the search paths.
#
# Note that the header path has changed from SDL2/SDL.h to just SDL.h
# This needed to change because "proper" SDL convention
# is #include "SDL.h", not &lt;SDL2/SDL.h&gt;. This is done for portability
# reasons because not all systems place things in SDL2/ (see FreeBSD).

#=============================================================================
# Copyright 2003-2009 Kitware, Inc.
#
# Distributed under the OSI-approved BSD License (the "License");
# see accompanying file Copyright.txt for details.
#
# This software is distributed WITHOUT ANY WARRANTY; without even the
# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the License for more information.
#=============================================================================
# (To distribute this file outside of CMake, substitute the full
#  License text for the above reference.)

SET(SDL2TTF_SEARCH_PATHS
        ~/Library/Frameworks
        /Library/Frameworks
        /usr/local
        /usr
        /sw # Fink
        /opt/local # DarwinPorts
        /opt/csw # Blastwave
        /opt
)

FIND_PATH(SDL2TTF_INCLUDE_DIR SDL_ttf.h
        HINTS
        $ENV{SDL2TTFDIR}
        PATH_SUFFIXES include/SDL2 include
        PATHS ${SDL2TTF_SEARCH_PATHS}
)

FIND_LIBRARY(SDL2TTF_LIBRARY_TEMP
        NAMES SDL2_ttf
        HINTS
        $ENV{SDL2TTFDIR}
        PATH_SUFFIXES lib64 lib
        PATHS ${SDL2TTF_SEARCH_PATHS}
)

IF(NOT SDL2TTF_BUILDING_LIBRARY)
    IF(NOT ${SDL2TTF_INCLUDE_DIR} MATCHES ".framework")
        # Non-OS X framework versions expect you to also dynamically link to
        # SDL2TTFmain. This is mainly for Windows and OS X. Other (Unix) platforms
        # seem to provide SDL2TTFmain for compatibility even though they don't
        # necessarily need it.
        FIND_LIBRARY(SDL2TTFMAIN_LIBRARY
                NAMES SDL2_ttf
                HINTS
                $ENV{SDL2TTFDIR}
                PATH_SUFFIXES lib64 lib
                PATHS ${SDL2TTF_SEARCH_PATHS}
        )
    ENDIF(NOT ${SDL2TTF_INCLUDE_DIR} MATCHES ".framework")
ENDIF(NOT SDL2TTF_BUILDING_LIBRARY)

# SDL2TTF may require threads on your system.
# The Apple build may not need an explicit flag because one of the
# frameworks may already provide it.
# But for non-OSX systems, I will use the CMake Threads package.
IF(NOT APPLE)
    FIND_PACKAGE(Threads)
ENDIF(NOT APPLE)

# MinGW needs an additional library, mwindows
# It's total link flags should look like -lmingw32 -lSDL2TTFmain -lSDL2TTF -lmwindows
# (Actually on second look, I think it only needs one of the m* libraries.)
IF(MINGW)
    SET(MINGW32_LIBRARY mingw32 CACHE STRING "mwindows for MinGW")
ENDIF(MINGW)

IF(SDL2TTF_LIBRARY_TEMP)
    # For SDL2TTFmain
    IF(NOT SDL2TTF_BUILDING_LIBRARY)
        IF(SDL2TTFMAIN_LIBRARY)
            SET(SDL2TTF_LIBRARY_TEMP ${SDL2TTFMAIN_LIBRARY} ${SDL2TTF_LIBRARY_TEMP})
        ENDIF(SDL2TTFMAIN_LIBRARY)
    ENDIF(NOT SDL2TTF_BUILDING_LIBRARY)

    # For OS X, SDL2TTF uses Cocoa as a backend so it must link to Cocoa.
    # CMake doesn't display the -framework Cocoa string in the UI even
    # though it actually is there if I modify a pre-used variable.
    # I think it has something to do with the CACHE STRING.
    # So I use a temporary variable until the end so I can set the
    # "real" variable in one-shot.
    IF(APPLE)
        SET(SDL2TTF_LIBRARY_TEMP ${SDL2TTF_LIBRARY_TEMP} "-framework Cocoa")
    ENDIF(APPLE)

    # For threads, as mentioned Apple doesn't need this.
    # In fact, there seems to be a problem if I used the Threads package
    # and try using this line, so I'm just skipping it entirely for OS X.
    IF(NOT APPLE)
        SET(SDL2TTF_LIBRARY_TEMP ${SDL2TTF_LIBRARY_TEMP} ${CMAKE_THREAD_LIBS_INIT})
    ENDIF(NOT APPLE)

    # For MinGW library
    IF(MINGW)
        SET(SDL2TTF_LIBRARY_TEMP ${MINGW32_LIBRARY} ${SDL2TTF_LIBRARY_TEMP})
    ENDIF(MINGW)

    # Set the final string here so the GUI reflects the final state.
    SET(SDL2TTF_LIBRARY ${SDL2TTF_LIBRARY_TEMP} CACHE STRING "Where the SDL2TTF Library can be found")
    # Set the temp variable to INTERNAL so it is not seen in the CMake GUI
    SET(SDL2TTF_LIBRARY_TEMP "${SDL2TTF_LIBRARY_TEMP}" CACHE INTERNAL "")
ENDIF(SDL2TTF_LIBRARY_TEMP)

INCLUDE(FindPackageHandleStandardArgs)

FIND_PACKAGE_HANDLE_STANDARD_ARGS(SDL2TTF REQUIRED_VARS SDL2TTF_LIBRARY SDL2TTF_INCLUDE_DIR)

解决步骤

1. 修正路径变量匹配问题

你的CMakeLists.txt中定义的路径变量是SDL2_TTF_PATH，但FindSDL2TTF.cmake仅读取环境变量SDL2TTFDIR，两者未关联。修改FindSDL2TTF.cmake中的路径查找逻辑，加入${SDL2_TTF_PATH}作为提示路径：

# 修改头文件查找部分
FIND_PATH(SDL2TTF_INCLUDE_DIR SDL_ttf.h
        HINTS
        $ENV{SDL2TTFDIR} ${SDL2_TTF_PATH}
        PATH_SUFFIXES include/SDL2 include
        PATHS ${SDL2TTF_SEARCH_PATHS}
)

# 修改库文件查找部分
FIND_LIBRARY(SDL2TTF_LIBRARY_TEMP
        NAMES SDL2_ttf
        HINTS
        $ENV{SDL2TTFDIR} ${SDL2_TTF_PATH}
        PATH_SUFFIXES lib64 lib
        PATHS ${SDL2TTF_SEARCH_PATHS}
)

2. 验证库文件与头文件路径

确认C:/libs/SDL2_ttf-2.22.0/x86_64-w64-mingw32目录结构符合预期：

include/SDL2/SDL_ttf.h 或 include/SDL_ttf.h 存在
lib/目录下存在libSDL2_ttf.a、libSDL2_ttf.dll.a或SDL2_ttf.dll（对应静态/动态库）

3. 清理冗余的TTFMain库查找逻辑

当前FindSDL2TTF.cmake中查找SDL2TTFMAIN_LIBRARY时使用的名称是SDL2_ttf，与主库重名，会导致重复查找。若你的MinGW版本SDL2_ttf没有单独的SDL2_ttfmain库，可直接注释掉这部分代码：

# IF(NOT SDL2TTF_BUILDING_LIBRARY)
#     IF(NOT ${SDL2TTF_INCLUDE_DIR} MATCHES ".framework")
#         FIND_LIBRARY(SDL2TTFMAIN_LIBRARY
#                 NAMES SDL2_ttf
#                 HINTS
#                 $ENV{SDL2TTFDIR} ${SDL2_TTF_PATH}
#                 PATH_SUFFIXES lib64 lib
#                 PATHS ${SDL2TTF_SEARCH_PATHS}
#         )
#     ENDIF(NOT ${SDL2TTF_INCLUDE_DIR} MATCHES ".framework")
# ENDIF(NOT SDL2TTF_BUILDING_LIBRARY)

4. 改用官方CMake配置（可选）

如果你的SDL2_ttf库包含官方CMake配置文件（位于lib/cmake/SDL2_ttf/），可放弃自定义Find模块，直接使用如下配置：

# 在CMakeLists.txt中替换原find_package部分
set(SDL2_TTF_DIR "C:/libs/SDL2_ttf-2.22.0/x86_64-w64-mingw32/lib/cmake/SDL2_ttf")
find_package(SDL2TTF REQUIRED CONFIG)

# 替换include_directories和target_link_libraries
target_link_libraries(${PROJECT_NAME} ${SDL2_LIBRARY} ${SDL2_IMAGE_LIBRARIES} SDL2::SDL2_ttf)

此方式无需手动设置包含目录，CMake会自动处理依赖。

内容的提问来源于stack exchange，提问作者Axilleas Xoumkoslis

CMake无法找到SDL2TTF包问题求助（附配置文件）

问题现象 #

用户配置文件 #

CMakeLists.txt #

FindSDL2TTF.cmake #

解决步骤 #

1. 修正路径变量匹配问题 #

2. 验证库文件与头文件路径 #

3. 清理冗余的TTFMain库查找逻辑 #

4. 改用官方CMake配置（可选） #