WSL下CMake集成mariadb-connector-cpp报错找不到libmariadb.so.3

参考mariadb-connector-cpp官方文档，在Visual Studio中使用C++20、CMake面向WSL平台开发时，程序运行出现共享库加载错误，提示无法找到libmariadb.so.3文件。

按照官方给出的Debian/Ubuntu平台构建指引，在WSL中完成mariadb-connector-cpp的编译安装，库文件与头文件安装路径对应如下截图：

初始编写的CMake配置如下：

find_package(mariadbcpp)
include_directories("/usr/local/include/mariadb")
link_directories("/usr/local/lib/mariadb")
target_link_libraries(${PROJECT_NAME} mariadbcpp)

程序运行时抛出错误：

error while loading shared libraries: libmariadb.so.3: cannot open shared object file: No such file or directory

已尝试的无效操作：

• 执行命令更新动态链接库缓存：

sudo /sbin/ldconfig -v

• 在顶层CMake配置中添加RPATH相关配置：

SET(CMAKE_SKIP_BUILD_RPATH  FALSE)
SET(CMAKE_BUILD_WITH_INSTALL_RPATH FALSE) 
SET(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
SET(CMAKE_INSTALL_RPATH "/usr/local/lib/mariadb")

按以下顺序操作即可解决问题：

• 第一步：定位libmariadb.so.3的真实存放路径
  mariadb-connector-cpp编译安装时，其依赖的底层C客户端库libmariadb.so.3默认不会存放在/usr/local/lib/mariadb根目录，通常会落在/usr/local/lib/mariadb/plugin子目录，或系统默认库路径/usr/lib/x86_64-linux-gnu/下。执行以下命令全局搜索文件位置：

  sudo find / -name "libmariadb.so.3"
  

• 第二步：更新系统动态链接库缓存
  若搜索结果显示文件不在系统默认识别的库路径下，执行以下操作：
  1. 新建mariadb的动态库配置文件：

     sudo nano /etc/ld.so.conf.d/mariadb.conf
     

  2. 将libmariadb.so.3所在的完整路径写入文件，例如文件存放在plugin子目录则写入：

     /usr/local/lib/mariadb
     /usr/local/lib/mariadb/plugin
     

  3. 保存退出后重新执行命令刷新缓存：

     sudo ldconfig
     

• 第三步：修正CMake配置错误
  原有配置存在两处核心问题：一是手动指定头文件、库路径的写法冗余，容易出现路径传递不一致；二是RPATH配置仅对make install安装后的程序生效，直接在构建目录运行可执行文件时不会加载配置的路径。修正后的最小可用配置如下：

  cmake_minimum_required(VERSION 3.16)
  project(your_project CXX)
  set(CMAKE_CXX_STANDARD 20)
  
  # 配置构建阶段、安装阶段均生效的RPATH
  set(CMAKE_SKIP_BUILD_RPATH FALSE)
  set(CMAKE_BUILD_WITH_INSTALL_RPATH TRUE)
  set(CMAKE_BUILD_RPATH_USE_ORIGIN TRUE)
  set(CMAKE_INSTALL_RPATH "/usr/local/lib/mariadb;/usr/local/lib/mariadb/plugin")
  set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
  
  find_package(mariadbcpp REQUIRED)
  add_executable(${PROJECT_NAME} 替换为你的项目源文件列表)
  # 使用现代CMake导入目标链接，自动传递头文件、库依赖、路径信息
  target_link_libraries(${PROJECT_NAME} PRIVATE mariadbcpp::mariadbcpp)
  

• 第四步：验证链接有效性
  重新编译完成后，进入构建输出目录执行以下命令检查依赖：

  ldd 替换为你的可执行文件名 | grep mariadb
  

  若输出中libmariadb.so.3后显示正确的绝对路径，无not found标记，说明配置生效，程序可正常启动。
• 额外排查点：如果通过Visual Studio直接远程连接WSL运行程序，需要检查VS启动配置中是否自定义覆盖了LD_LIBRARY_PATH环境变量，若存在自定义配置，需要将libmariadb.so.3所在路径追加到该变量中。

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