C++ 引入第三方库(三)：使用 CMake 导入

使用 CMake 导入库其实应该称为使用 CMake 将第三方库安装到 CMake 的 install 目录下。解释一下首先CMake 有着与 Maven 类似的 install 机制通过cmake --install命令可以将本地项目安装到CMAKE_INSTALL_PREFIX目录下这个CMAKE_INSTALL_PREFIX是一个变量用户可以手动设定如果不显示设置它在 Windows 下的默认路径是C:/Program Files (x86)/${PROJECT_NAME}也就是说默认情况下C:/Program Files (x86)类似于 Maven 的%USERPROFILE%/.m2/repository目录。另一方面为了和 CMake 生态集成大多数的第三方库会主动提供一组符合 CMake 规范的配置文件一组 .cmake 文件当第三方库通过cmake --install在本地安装之后就会在安装目录中生成这些文件CMake 可以通过这些文件自动定位库的头文件和库文件如此一来用户只需在项目的 CMakeLists.txt 里使用find_package声明一下 CMake 就能自动找到库的相关资源而不必再向像 方式二手动导入库和头文件 那样明确指出头文件路径和链接库路径这种导入方式就是使用 CMake 导入即通过 CMake 将第三方库以 CMake 的管理形式安装到本地。使用 CMake 导入库的方法被认为是仅次于包管理器的一种现代化的 C 包引入机制不过由于CMake 的安装是从源码编译开始的只有经过源码编译后才能得到关键的 xxxConfig.cmake 文件这大大削弱了这种方式的便捷性。这和 Maven 的 install 有一个很大的不同Maven 的 install 只需要 Jar 包和 pom.xml 就能把一个库安装到 repo 中但 CMake 只能从源代码编译开始。本文我们以 spdlog 这个库为例完整地演示一下如何使用 CMake 导入第三方库。1. 工作原理通过 CMake 导入第三方库的工作原理可简单概括为让库自己提供一个符合 CMake 规范的文件把它的包含的头文件和库文件的存放位置提供一下再让 CMake 能自动找到这个文件那么用户就不用像方式三那样再手动指明头文件存和链接库的路径了。实现上述目标主要靠 find_package 命令和 xxxConfig.cmake 文件。find_package 会在以下几个约定的位置根据提供的包名查找一个名为PackageNameConfig.cmake的文件优先级路径类型示例1通过变量指定路径set(PackageName_DIR /path/to/pkg-dir)1或-DPackageName_DIR...2系统默认路径/usr/local/C:/Program Files (x86)/3环境变量CMake 会查找 PATH、CMAKE_PREFIX_PATH 或 CMAKE_FRAMEWORK_PATH 等环境变量对应的安装路径4模块路径首先在 CMAKE_MODULE_PATH 变量定义的路径下查找 Find.cmake 文件最后在 CMake 安装目录中搜索找到后在这个PackageNameConfig.cmake文件包含着如下若干重要信息头文件目录在哪里.lib 文件在哪里Debug 用哪个 libRelease 用哪个 lib依赖哪些其他库对外目标名称spdlog::spdlog进而 CMake 知道该怎样使用这个库了不管是取得头文件也好还是链接时去哪里找链接库信息都有了。如果PackageNameConfig.cmake文件、inlude 和 lib 文件都是现成的那么使用 CMake 导入库应是非常简单丝滑的不过如开头所述实际上操作起来去极为繁琐因为几乎所有开源 C 库的发行包都不会包含PackageNameConfig.cmake文件它们只会提供PackageNameConfig.cmake.in文件这是一个模板文件只有经 CMake 构建和安装后才会得到PackageNameConfig.cmake文件原因很简单因为安装路径、库路径、编译配置这些信息只有在编译安装后才能确定所以一个很悲伤的发现使用纯 CMake 方式导入第三方库本身很美好但为了得到PackageNameConfig.cmake文件却不不得从源码编译开始2. 环境准备我们需要设置两个系统环境变量CMAKE_INSTALL_PREFIX默认安装路径 和CMAKE_PREFIX_PATH默认查找路径这并不是必须但建议还是要配置一下。主要的原因是通常我们应该让 CMake 的包安装在一个统一的默认位置查找包时也到这个统一的位置查找就像 Maven 的%USERPROFILE%/.m2/repository一样形成一个系统级的“本地程序库”在 64位 Windows 系统下这个默认的位置是C:/Program Files (x86)但是由于写入权限的限制使用这个默认位置安转包时会报如下错误file INSTALL cannot make directory “C:/Program Files (x86)/spdlog/include”并且C:/Program Files (x86)本身就不适合作为“本地程序库”的目录所以建议还是显式地配置一下。本文我们仿照 Maven 的作法创建一个%USERPROFILE%/.cmake/repository作为我们的CMAKE_INSTALL_PREFIX默认安装路径 和CMAKE_PREFIX_PATH默认查找路径3. 编译安装打开 spdlog 的 release 页面https://github.com/gabime/spdlog/releases下载源代码并解压进入源代码的根目录执行如下命令进行编译和安装(注意逐条执行不要一次性粘贴:: 在源代码目录下创建 build 子目录 rd /S /Q build mkdir build cd build :: 针对上一级工程目录生成工程文件特别地要指名安装位置 cmake .. :: 若未配置环境变量 CMAKE_INSTALL_PREFIX则需手动指定一个目录 :: cmake .. -DCMAKE_INSTALL_PREFIXC:\Lib\spdlog :: 编译并安装 Debug 库 cmake --build . --config Debug cmake --install . --config Debug :: 编译并安装 Release 库 cmake --build . --config Release cmake --install . --config Release全部执行无误后检查一下%USERPROFILE%/.cmake/repository下是否有已安装好生成的头文件、库文件和 spdlogConfig.cmake如果使用自己手动指定的目录则应去对应目录下查找正常情况该目录是这样的%USERPROFILE%/.cmake/repository ├── include │ └── spdlog │ ├── async.h │ ├── ... │ └── version.h └── lib ├── cmake │ └── spdlog │ ├── spdlogConfig.cmake │ ├── spdlogConfigTargets-debug.cmake │ ├── spdlogConfigTargets-release.cmake │ ├── spdlogConfigTargets.cmake │ └── spdlogConfigVersion.cmake ├── pkgconfig │ └── spdlog.pc ├── spdlog.lib └── spdlogd.lib4. 编辑 CMakeLists.txt新建一个项目在 CMakeLists.txt 中插入如下内容cmake_minimum_required(VERSION 3.20) # 自动将每个目标的当前源码目录添加到包含路径 set(CMAKE_INCLUDE_CURRENT_DIR ON) # 如前面 build 时手动配置了 CMAKE_INSTALL_PREFIX # 则此时必须显式地指出目标库的位置 # set(spdlog_DIR C:/Lib/spdlog/lib/cmake/spdlog/) # 查找库 find_package(spdlog REQUIRED) # 创建可执行程序 add_executable(add-3rd-lib-demo-2 main.cpp) # 链接 spdlog 库 target_link_libraries(add-3rd-lib-demo-2 PRIVATE spdlog::spdlog)注意如果说 find_package 中的spdlog是我们自己起的库名那么spdlog_DIR则是一个约定的变量名不可随意修改它的格式必须是PackageName_DIR包括大小写也是敏感的否则编译时就会报找不到 xxxConfig.cmake 错误CMake 是严格按照上述约定变量名提供的路径去查找文件的。如果不想定义这个变量就应该把库安装到默认路径下。可到导入目标spdlog::spdlog则是“写死”的任何大小写改动都会报错5. 运行程序在项目中添加一个main.cpp执行运行#includespdlog/spdlog.hintmain(){spdlog::info(Hello spdlog!);spdlog::warn(This is a warning message);spdlog::error(This is an error);return0;}输出[2026-04-03 21:30:39.461] [info] Hello spdlog! [2026-04-03 21:30:39.463] [warning] This is a warning message [2026-04-03 21:30:39.465] [error] This is an error关联阅读《C 引入第三方库(一)直接引入源文件》《C 引入第三方库(二)手动导入库和头文件》《C 引入第三方库(三)使用 CMake 导入》《C 引入第三方库(四)使用包管理器》这里有一个非常“尴尬”的地方这个变量名中的DIR部分是只能大写如果你用一个小写的包名去和它组合就会及其的难看例如spdlog_DIR但如果你换成大写例如SPDLOG_DIR由于它是代表的是报名且 CMake 是大小写敏感的那么在 CMakeLists.txt 中任何使用这个包名的地方你都得使用SPDLOG而不可以是spdlog。 ↩︎