如何在CLion的C++项目中引入.so共享库并解决链接错误

一、确保头文件声明与库中函数完全匹配 #

你的头文件（比如mylib.hpp）必须和.so库中实现的函数严格一致，包括函数名、参数类型、返回值类型：

#include <string>

// 必须和库内的函数实现完全匹配
std::string say_hello(int num);

二、正确配置CMakeLists.txt #

在CLion项目的CMakeLists中，需要完成「指定头文件路径」「导入.so库」「链接库到可执行文件」三个步骤，以下是两种常用配置方式：

方式1：使用find_library查找库 #

假设你的.so库文件名为libmylib.so，存放在../my_lib/lib/目录，头文件在../my_lib/include/目录：

cmake_minimum_required(VERSION 3.20)
project(MyProject)

set(CMAKE_CXX_STANDARD 17)

# 1. 添加头文件搜索目录，让编译器找到mylib.hpp
target_include_directories(${PROJECT_NAME} PRIVATE ../my_lib/include)

# 2. 查找指定目录下的.so库
# 参数说明：变量名、库名（去掉lib前缀和.so后缀）、搜索路径
find_library(MY_LIB mylib PATHS ../my_lib/lib NO_DEFAULT_PATH)

# 验证是否找到库（可选，用于排查问题）
message(STATUS "Found library: ${MY_LIB}")

# 3. 创建可执行文件并链接库
add_executable(${PROJECT_NAME} main.cpp)
target_link_libraries(${PROJECT_NAME} PRIVATE ${MY_LIB})

方式2：直接导入指定路径的.so文件 #

如果find_library无法自动识别，可直接指定库文件路径：

cmake_minimum_required(VERSION 3.20)
project(MyProject)

set(CMAKE_CXX_STANDARD 17)

# 1. 添加头文件搜索目录
target_include_directories(${PROJECT_NAME} PRIVATE ../my_lib/include)

# 2. 导入外部共享库
add_library(mylib SHARED IMPORTED)
# 设置库文件的绝对/相对路径
set_target_properties(mylib PROPERTIES
    IMPORTED_LOCATION ../my_lib/lib/libmylib.so
)

# 3. 创建可执行文件并链接库
add_executable(${PROJECT_NAME} main.cpp)
target_link_libraries(${PROJECT_NAME} PRIVATE mylib)

三、在main.cpp中调用库函数 #

直接包含头文件后调用即可，确保调用方式和声明一致：

#include "mylib.hpp"
#include <iostream>

int main() {
    std::string res = say_hello(456);
    std::cout << res << std::endl;
    return 0;
}

四、排查"undefined reference"错误的关键点 #

1. 函数声明不匹配：检查头文件的函数名、参数类型、返回值是否和库内实现完全一致，哪怕是int和long这种细微差异都会导致链接失败。
2. 库架构不兼容：确保你的CLion项目架构（x86_64/arm64）和.so库的编译架构一致，比如64位项目不能链接32位库。
3. C++名字修饰问题：如果.so库是用extern "C"编译的（通常为了给C程序调用），但你的头文件没对应声明，会导致链接时找不到修饰后的名字。这种情况下需要在头文件中包裹声明：

   #ifdef __cplusplus
   extern "C" {
   #endif
   
   // 注意：extern "C"不能用于返回/接收C++特有类型（比如std::string）的函数，这类库必然是C++编译的，无需加此块
   const char* say_hello(int num);
   
   #ifdef __cplusplus
   }
   #endif
   

4. CMake未正确找到库：通过message(STATUS "Found library: ${MY_LIB}")查看是否输出了库的路径，如果是空值，说明路径配置错误，检查PATHS后的路径是否正确。
5. 运行时库查找问题：编译链接成功后运行时提示找不到.so，可在CMake中添加RUNPATH配置，让程序自动加载指定目录的库：

   set_target_properties(${PROJECT_NAME} PROPERTIES
       INSTALL_RPATH "../my_lib/lib"
       BUILD_WITH_INSTALL_RPATH ON
   )
   

内容的提问来源于stack exchange，提问作者Romário Mondlane El Shaarawy