CMakeLists编译库成功但无法链接至可执行文件的问题排查

问题现象 #

在macOS上用CMake构建C++项目，手动引入vendored的SDL系列库（放弃find_package），生成Makefile无报错，但编译链接时出现x86_64架构的未定义符号错误，缺失的符号均来自iOS相关的CHHaptic、GCController等框架类，错误示例如下：

[ 49%] Linking C shared library libSDL2-2.0.dylib
Undefined symbols for architecture x86_64:
  "_CHHapticDynamicParameterIDHapticIntensityControl", referenced from:
      -[SDL_RumbleMotor setIntensity:] in SDL_mfijoystick.m.o
  "_CHHapticEventParameterIDHapticIntensity", referenced from:
      -[SDL_RumbleMotor setIntensity:] in SDL_mfijoystick.m.o
  "_CHHapticEventTypeHapticContinuous", referenced from:
      -[SDL_RumbleMotor setIntensity:] in SDL_mfijoystick.m.o
  "_GCControllerDidConnectNotification", referenced from:
      _IOS_JoystickInit in SDL_mfijoystick.m.o
      _IOS_JoystickQuit in SDL_mfijoystick.m.o

  ...

  "_OBJC_CLASS_$_CHHapticDynamicParameter", referenced from:
      objc-class-ref in SDL_mfijoystick.m.o
  "_OBJC_CLASS_$_CHHapticEvent", referenced from:
      objc-class-ref in SDL_mfijoystick.m.o
  "_OBJC_CLASS_$_CHHapticEventParameter", referenced from:
      objc-class-ref in SDL_mfijoystick.m.o
  "_OBJC_CLASS_$_CHHapticPattern", referenced from:
      objc-class-ref in SDL_mfijoystick.m.o
  "_OBJC_CLASS_$_GCColor", referenced from:
      objc-class-ref in SDL_mfijoystick.m.o
  "_OBJC_CLASS_$_GCController", referenced from:
      objc-class-ref in SDL_mfijoystick.m.o
  "_OBJC_CLASS_$_GCControllerAxisInput", referenced from:
      objc-class-ref in SDL_mfijoystick.m.o
  "_OBJC_CLASS_$_GCControllerButtonInput", referenced from:
      objc-class-ref in SDL_mfijoystick.m.o
ld: symbol(s) not found for architecture x86_64

当前使用的CMake脚本如下：

cmake_minimum_required(VERSION 3.10)

set(CMAKE_OSX_ARCHITECTURES "x86_64;arm64")
set(CMAKE_MACOSX_RPATH 1)

set(OutputPath "${CMAKE_SOURCE_DIR}/bin/${CMAKE_SYSTEM_NAME}")

set(CMAKE_ARCHIVE_OUTPUT_DIR "${OutputPath}/staticlibs")
set(CMAKE_LIBRARY_OUTPUT_DIR "${OutputPath}")
set(CMAKE_RUNTIME_OUTPUT_DIR "${OutputPath}")

set(CMAKE_FIND_FRAMEWORK NEVER)

set(TGUI_BACKEND SDL_RENDERER)
set(TGUI_BUILD_FRAMEWORK FALSE)

project(Tutorial VERSION 1.1
        DESCRIPTION "Project" 
        LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED True)

#
# Setting lists for convenience:
#

set(SourceList
    src/main.cpp
    src/graphics.cpp
    src/main.h
    src/graphics.h
    src/version.h
    src/files.cpp
    src/files.h
    src/mainExclusive.h
    src/include/tinyfiledialogs.cpp
    src/include/tinyfiledialogs.h
)

set (Libraries
    src/include/SDL2
    src/include/SDL2_image
    src/include/SDL2_ttf
    src/include/TGUI-1.3.0
) 

set (LibraryNames
    SDL2
    SDL2_image
    SDL2_ttf
    TGUI
)

add_executable(${PROJECT_NAME} MACOSX_BUNDLE ${SourceList})

# Read the Libraries list to determine subdirectories to add

foreach(Project IN LISTS Libraries)
    #include_directories(${Project})
    if(NOT TARGET ${Project})
        add_subdirectory(${Project})
    endif()
endforeach()

# Read LibraryNames to link the libraries by their actual name

foreach(Name IN LISTS LibraryNames)
    target_link_libraries(${PROJECT_NAME} ${Name})
endforeach()

问题原因 #

SDL的SDL_mfijoystick.m是为iOS平台实现的摇杆驱动代码，但在macOS构建时被错误编译并参与链接，而这些代码依赖的iOS系统框架（如GameController、CoreHaptics）并未被引入macOS的链接流程，导致符号缺失。

解决方案 #

1. 强制SDL仅构建macOS平台代码 #

在添加SDL子目录前，明确设置SDL的平台相关编译选项，禁止iOS代码参与构建：

# 配置SDL仅针对macOS构建，禁用iOS相关模块
set(SDL_IOS OFF CACHE BOOL "" FORCE)
set(SDL_JOYSTICK_MFI OFF CACHE BOOL "" FORCE)

2. 链接macOS所需的系统框架（如果仍需MFi摇杆支持） #

如果确实需要在macOS上支持MFi设备，需手动链接对应的系统框架：

# 链接GameController和CoreHaptics框架
target_link_libraries(${PROJECT_NAME}
    "-framework GameController"
    "-framework CoreHaptics"
)

3. 优化CMake脚本结构 #

• 避免全局设置CMAKE_FIND_FRAMEWORK NEVER，SDL构建可能需要查找macOS系统框架，可改为针对特定目标设置，或在SDL子目录前临时调整：

  # 在添加SDL前临时允许查找框架
  set(CMAKE_FIND_FRAMEWORK BEFORE)
  add_subdirectory(src/include/SDL2)
  # 恢复原设置（如果需要）
  set(CMAKE_FIND_FRAMEWORK NEVER)
  

• 移除冗余的全局设置，尽量使用目标级别的配置（如target_include_directories替代全局include_directories）

修改后的关键CMake代码片段 #

# ... 其他原有配置 ...

# 先配置SDL的平台选项
set(SDL_IOS OFF CACHE BOOL "" FORCE)
set(SDL_JOYSTICK_MFI OFF CACHE BOOL "" FORCE)

# 添加子目录
foreach(Project IN LISTS Libraries)
    if(NOT TARGET ${Project})
        add_subdirectory(${Project})
    endif()
endforeach()

# 链接库和必要框架
foreach(Name IN LISTS LibraryNames)
    target_link_libraries(${PROJECT_NAME} ${Name})
endforeach()

# 如果需要MFi摇杆支持，添加框架链接
# target_link_libraries(${PROJECT_NAME} "-framework GameController" "-framework CoreHaptics")

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