CMake编译错误排查：如何链接共享库？

嘿，我经常碰到CMake链接共享库的问题，虽然你没贴具体的错误信息，但我可以给你列几个最常见的排查方向和解决方法，应该能帮你搞定：

1. 先确认共享库的CMake配置是否正确 #

• 如果是项目内部的共享库：要确保库的CMakeLists.txt里用了正确的构建命令，比如：

  # 构建共享库lib1
  add_library(lib1 SHARED src/lib1.cpp include/lib1.h)
  # 导出库的头文件路径，方便主程序引用
  target_include_directories(lib1 PUBLIC include)
  

  同时主程序的CMakeLists.txt要通过add_subdirectory()引入库的子目录，比如add_subdirectory(lib1)，这样CMake才能识别到lib1这个目标。
• 如果是外部的共享库：需要用find_package()或者find_library()定位到库文件，比如：

  # 查找外部共享库lib1
  find_library(LIB1_LIBRARY NAMES lib1.so PATHS /usr/local/lib /path/to/your/lib)
  find_path(LIB1_INCLUDE_DIR lib1.h PATHS /usr/local/include /path/to/your/include)
  # 确认找到库和头文件
  if(NOT LIB1_LIBRARY OR NOT LIB1_INCLUDE_DIR)
      message(FATAL_ERROR "Could not find lib1!")
  endif()
  

2. 正确使用target_link_libraries链接库 #

这是最容易踩坑的地方，一定要注意语法和目标名的正确性：

# 先定义主程序目标
add_executable(main_app src/main.cpp)
# 链接项目内部的共享库（用库的目标名）
target_link_libraries(main_app PRIVATE lib1 lib2)
# 如果是外部库，用find_library得到的变量
# target_link_libraries(main_app PRIVATE ${LIB1_LIBRARY} ${LIB2_LIBRARY})

• 注意PRIVATE/PUBLIC/INTERFACE的区别：如果主程序只在.cpp文件里用库的功能，用PRIVATE就够了；如果主程序的头文件里也用到了库的类型，就得用PUBLIC。

3. 排查头文件路径问题 #

如果编译时出现fatal error: lib1.h: No such file or directory的错误，要给主程序添加库的头文件路径：

# 项目内部库的情况，直接用库的目标名获取头文件路径
target_include_directories(main_app PRIVATE ${lib1_SOURCE_DIR}/include ${lib2_SOURCE_DIR}/include)
# 外部库的情况，用find_path得到的变量
# target_include_directories(main_app PRIVATE ${LIB1_INCLUDE_DIR} ${LIB2_INCLUDE_DIR})

4. 解决链接阶段的未定义符号错误 #

如果出现undefined reference to xxx的错误，通常是这几个原因：

• 链接的库目标名写错了，或者库本身没正确编译出对应的符号（比如库的代码里没导出符号：Linux下如果用了-fvisibility=hidden，需要给要导出的函数加__attribute__((visibility("default")))；Windows下需要__declspec(dllexport)）。
• 链接顺序不对：GCC下依赖的库要放在被依赖的后面，但CMake的target_link_libraries通常会自动处理这个问题，除非你手动写了原始的链接命令。

5. 清理缓存后重新构建 #

有时候build目录里的旧缓存会导致奇怪的错误，先彻底清理再重新构建：

cd build
rm -rf ./*
cmake ..
make -j

6. 查看详细编译日志定位问题 #

如果上面的方法都没用，运行make VERBOSE=1查看完整的编译和链接命令，这样能清楚看到：链接时有没有用到正确的库文件、路径是否正确、编译参数有没有问题，根据日志就能精准定位错误了。

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