target_link_libraries传入目标与.a文件的差异及链接报错原因

使用target_link_libraries()链接CMake目标时编译运行一切正常，但直接链接该目标生成的.a静态库文件时，编译通过却出现大量undefined reference to或multiple definition to链接错误。

原有CMakeLists.txt：

file (sources a.cc b.cc ...)
add_executable(my_project ${sources}) 

为支持其他项目，调整为生成静态库的CMakeLists.txt：

file (sources a.cc b.cc ...)
add_library(my_project ${sources})

add_executable(another_project main.cc)
target_link_libraries(another_project my_project)

此方式运行正常，但改为直接链接.a文件后出错：

target_link_libraries(another_project libmy_project.a)

想了解：当传入CMake目标给target_link_libraries时，具体发生了什么？

当你在target_link_libraries中传入CMake目标（比如my_project）时，CMake做的远不止简单传递静态库文件路径给链接器，它还会自动处理一系列关键配置：

• 传递编译上下文：CMake会把my_project目标的编译选项、预定义宏、头文件路径等配置自动同步到another_project。比如如果my_project编译时指定了-std=c++17标准或-DENABLE_FEATURE宏，这些设置会被应用到链接它的目标，避免因编译标准、宏定义不一致导致的符号不匹配——这是undefined reference错误的常见诱因。
• 自动处理依赖链：如果my_project本身依赖其他库（比如通过target_link_libraries(my_project other_lib)添加的依赖），CMake会自动将这些间接依赖也链接到another_project中。直接链接.a文件时，CMake不会识别这些隐藏依赖，导致链接时缺失必要符号。
• 优化链接逻辑：CMake会根据目标类型（静态/动态库）自动调整链接器参数，比如静态库的符号可见性、链接顺序等。直接指定.a文件时，链接器会按原始顺序处理归档文件，容易出现符号重复定义（如多个库导出相同符号）或符号无法解析的问题。
• 适配平台差异：不同平台的静态库命名规则、链接参数存在差异（比如Windows为.lib，Linux为.a），CMake会自动适配这些细节；直接写死.a路径会跳过这种适配，可能导致链接器无法正确识别库文件。

简言之，CMake目标是包含编译配置、依赖关系、平台适配信息的完整实体，而.a文件只是编译后目标文件的归档，缺少这些关键上下文，因此直接链接会触发各类链接错误。

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