现代 CMake 模块化项目管理指南

现代 CMake 模块化项目管理指南

参考小彭老师的视频教程整理笔记，学习同时方便快速查阅，视频链接如下
【公开课】现代 CMake 模块化项目管理指南【C/C++】
对应课程 PPT 和源码见
https://github.com/parallel101/course
文件/目录组织规范

完整案例参考源码仓库
https://github.com/parallel101/course/tree/master/16/00
推荐的目录组织方式

1. .
2. ├── biology
3. │   ├── CMakeLists.txt
4. │   ├── include
5. │   │   └── biology
6. │   │       └── Animal.h
7. │   └── src
8. │       └── Animal.cpp
9. ├── CMakeLists.txt
10. └── pybmain
11.     ├── CMakeLists.txt
12.     ├── include
13.     │   └── pybmain
14.     │       └── myutils.h
15.     └── src
16.         └── main.cpp

复制代码

第一点，划分了 biology 和 pybmain 两个子项目，每个子项目在各自目录下各有自己的 CMakeLists.txt 文件。
第二点，所有子项目中都被划分为了 include 和 src 两个子目录，分别用来放头文件和源码文件，而其中 include 目录又套了一层项目名，这样可以避免头文件名称冲突。子项目的 CMakeLists.txt 文件中需要使用

1. target_include_directories(${PROJECT_NAME} PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)

复制代码

源码文件中这样写，

1. #include <biology/Animal.h>
2. #include <pybmain/myutils.h>

复制代码

第三点，推荐每个模块都有自己的命名空间，头文件中需要

1. #pragma once
2. namespace biology {
3. class Animal {
4. //...
5. };
6. }

复制代码

源码文件中需要

1. #include <biology/Animal.h>
3. namespace biology {
4. //...
5. };

复制代码

根项目的 CMakeLists.txt 配置

1. cmake_minimum_required(VERSION 3.15)
3. if (NOT CMAKE_BUILD_TYPE)
4.     set(CMAKE_BUILD_TYPE Release)
5. endif()
7. set(CMake_CXX_STANDARD 17)
8. set(CMAKE_CXX_STANDARD_REQUIRED ON)
9. set(CMAKE_CXX_EXTENSIONS OFF)
11. project(CppCMakeDemo LANGUAGES CXX)
13. add_subdirectory(biology)
14. add_subdirectory(pybmain)

复制代码

最后两行是关键，用来添加子项目，会调用子项目的 CMakeLists.txt 文件。
子项目的 CMakeLists.txt 配置

库文件的配置

1. # biology/CMakeLists.txt
2. file(GLOB_RECURSE srcs CONFIGURE_DEPENDS src/*.cpp include/*.h)
3. add_library(biology STATIC ${srcs})
4. target_include_directories(biology PUBLIC include)

复制代码

首先使用 GLOB_RECURSE 命令获取所有源码文件，然后使用 add_library 命令添加静态库，最后使用 target_include_directories 命令添加头文件搜索路径。

• PUBLIC 修饰符表示这个头文件搜索路径会被暴露给其他依赖这个库的项目，链接了 biology 库的 pybmain 项目也可以共享这个路径。
  
• 注意到我们将 .h 文件也一并添加到了 add_library 命令中，这样可以确保 .h 文件也会被添加到 IDE 中，方便查看。
  
• GLOB_RECURSE 相比 GLOB 允许匹配嵌套的目录。
  
• CONFIGURE_DEPENDS 选项表示如果源码文件发生变化，cmake --build build 会检测目录是否更新，有新文件则自动重新运行 cmake -B build 重新配置项目。
  

可执行文件的配置

1. # pybmain/CMakeLists.txt
2. file(GLOB_RECURSE srcs CONFIGURE_DEPENDS src/*.cpp include/*.h)
3. add_executable(pybmain ${srcs})
4. target_include_directories(pybmain PUBLIC include)
6. target_link_libraries(pybmain PUBLIC biology)

复制代码

基本和库文件的配置一致，只是使用 add_executable 命令添加可执行文件，使用 target_link_libraries 命令链接库文件。
CMake 的 include 功能

和 C/C++ 的 #include 一样，CMake 也有一个 include 命令，CMake 会在 CMAKE_MODULE_PATH 中搜索相应的 XXX.cmake 文件。

1. # ./CMakeLists.txt
2. set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
4. project(CppCMakeDemo LANGUAGES CXX)
6. include(MyUsefulFuncs)

复制代码

1. # cmake/MyUsefulFuncs.cmake
2. macro (my_add_target name type)
3.     # 用法：my_add_target(pybmain EXECUTABLE)
4.     file(GLOB_RECURSE srcs CONFIGURE_DEPENDS src/*.cpp src/*.h)
5.     if ("${type}" MATCHES "EXECUTABLE")
6.         add_executable(${name} ${srcs})
7.     else()
8.         add_library(${name} ${type} ${srcs})
9.     endif()
10.     target_include_directories(${name} PUBLIC include)
11. endmacro()
13. set(SOME_USEFUL_GLOBAL_VAR    ON)
14. set(ANOTHER_USEFUL_GLOBAL_VAR OFF)

复制代码

macro 和 function 的区别

• macro 相当于直接把代码粘贴过去，直接访问调用者的作用域。这里写的相对路径 include 和 src，是基于调用者所在路径。
  
• function 则是会创建一个闭包，优先访问定义者的作用域。这里写的相对路径 include 和 src，则是基于定义者所在路径。
  

include 和 add_subdirectory 的区别

• include 相当于直接把代码粘贴过去，直接访问调用者的作用域。这里创建的变量和外面共享，直接 set(key val) 则调用者也有 ${key} 这个变量了。
  
• function 中则是基于定义者所在路径，优先访问定义者的作用域。这里需要 set(key val PARENT_SCOPE) 才能修改到外面的变量。
  

第三方库/依赖项配置

主要讲解 find_package 命令，其官方文档为
https://cmake.org/cmake/help/latest/command/find_package.html
用法举例

1. # 查找名为 OpenCV 的包，找不到不报错，事后可以通过 ${OpenCV_FOUND} 查询是否找到。
2. find_package(OpenCV)
3. # 查找名为 OpenCV 的包，找不到不报错，也不打印任何信息。
4. find_package(OpenCV QUIET)
5. # 查找名为 OpenCV 的包，找不到就报错（并终止 cmake 进程，不再继续往下执行）。
6. find_package(OpenCV REQUIRED)    # 最常见用法
7. # 查找名为 OpenCV 的包，找不到就报错，且必须具有 OpenCV::core 和 OpenCV::videoio 这两个组件，如果没有这两个组件也会报错。
8. find_package(OpenCV REQUIRED COMPONENTS core videoio)
9. # 查找名为 OpenCV 的包，找不到就报错，可具有 OpenCV::core 和 OpenCV::videoio 这两个组件，没有这两组件不会报错，通过 ${OpenCV_core_FOUND} 查询是否找到 core 组件。
10. find_package(OpenCV REQUIRED OPTIONAL_COMPONENTS core videoio)

复制代码

find_package 原理

实际上 find_package(OpenCV) 是在找一个叫做 OpenCVConfig.cmake 的文件，这个文件是 OpenCV 项目提供的，用来告诉 cmake OpenCV 的安装路径和组件信息。
这个包配置文件由第三方库作者提供，在安装这个包时一并安装到系统中的，一般的约定是将其安装到 /usr/lib/cmake/XXX/ 目录下，其中 XXX 为包名。
Windows 系统下的搜索路径

1. <prefix>/
2. <prefix>/cmake/
3. <prefix>/<name>*/
4. <prefix>/<name>*/cmake/
5. <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/
6. <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/
7. <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/cmake/

复制代码

其中  是变量 ${CMAKE_PREFIX_PATH}，Windows 平台默认为 C:/Program Files， 是在 find_package( REQUIRED) 命令中指定的包名， 是系统的架构名。
Unix 系统下的搜索路径

1. <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/
2. <prefix>/(lib/<arch>|lib*|share)/<name>*/
3. <prefix>/(lib/<arch>|lib*|share)/<name>*/cmake/
4. <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/
5. <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/
6. <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/cmake/

复制代码

其中  是变量 ${CMAKE_PREFIX_PATH}，Unix 平台默认为 /usr， 是你在 find_package( REQUIRED) 命令中指定的包名， 是系统的架构，例如 x86_64-linux-gnu 或 i386-linux-gnu（用于伺候 Ubuntu 喜欢把库文件套娃在 /usr/lib/x86_64-linux-gnu 目录下）。
另外  可以有额外后缀，例如 find_package(Qt5) 可以在 Qt5.12.1/cmake 或者 Qt5xxx/cmake 目录下找到 Qt5Config.cmake 文件。
非标准路径安装的库

想让 CMake 找到非标准路径安装的库，本质上是定义好 NAME_DIR 变量，告诉 CMake 库文件的路径，然后再调用 find_package 命令。
例如可以直接在 CMakeLists.txt 中定义该变量，

1. # pybmain/CMakeLists.txt
2. set(OpenCV_DIR "/home/pyb/opencv/build")
3. find_package(OpenCV REQUIRED)

复制代码

这种方式对该项目有效，但是不便于开源分发，因其路径直接写死在 CMakeLists.txt 中，其他人要用的时候就会找不到该路径下的 OpenCVConfig.cmake 文件。
也可以设置环境变量

1. export OpenCV_DIR="/home/pyb/opencv/build"

复制代码

这种方式全局有效，但是不便于多版本共存，因为环境变量是全局的，如果要切换到其他版本的 OpenCV，就需要重新设置环境变量。
最好的方式是在调用 cmake 命令时定义该变量，例如

1. cmake -B build -DOpenCV_DIR="/home/pyb/opencv/build"

复制代码

虽然每次需要在命令行中输入，但是这种方式既不会污染全局环境，也不会污染项目的 CMakeLists.txt，而且可以方便的切换版本。并且 CMake 本身有缓存功能，只要没有删除 build 目录下的 CMakeCache.txt 文件，下次再运行 cmake -B build 时不输入该变量 CMake 也会自动读取缓存中的值。
未提供 Config 文件的第三方库

有一些库非常热门，但是并未提供 Config 文件，例如 Python，CUDA，Jemalloc 等，这时候就需要我们自己写 FindXXX.cmake 文件来查找该库，幸运的是 CMake 已经为我们提供了这些库的 FindXXX.cmake 文件，可以在 CMake 安装目录下的 share/cmake/Modules/ 目录下找到。
另外有一些库没有那么热门，CMake 也没有为我们提供 FindXXX.cmake 文件，这时候需要我们自己编写相应的 Find 文件，但是往往网上已经有人写过了，只需要搜索一下就可以找到，下面的链接是 Jemalloc 的 Find 文件
https://github.com/AcademySoftwareFoundation/openvdb/blob/master/cmake/FindJemalloc.cmake
这些文件有些使用的是古代 CMake 风格，有些是现代 CMake 风格，命名也不尽统一，但是一般都会有相应的说明文档，可以参考着使用。
指定 find_package 模式

find_package 命令有两种模式，一种是 MODULE 模式，一种是 CONFIG 模式。

• MODULE 模式，只会寻找 FindTBB.cmake 文件，而不会寻找 TBBConfig.cmake 文件，这种模式下，find_package 命令会在 CMAKE_MODULE_PATH（默认为 /usr/share/cmake/Modules）中搜索 FindTBB.cmake 文件
  1. find_package(TBB MODULE REQUIRED)

  复制代码
• CONFIG 模式，只会寻找 TBBConfig.cmake 文件，而不会寻找 FindTBB.cmake 文件，这种模式下，find_package 命令会在 ${CMAKE_PREFIX_PATH}/lib/cmake/TBB（默认为 /usr/lib/cmake/TBB）、${TBB_DIR} 和 $ENV{TBB_DIR} 中搜索 TBBConfig.cmake 文件
  1. find_package(TBB CONFIG REQUIRED)

  复制代码

不指定则两者都会尝试，默认先查找 Find 文件，如果找不到再查找 Config 文件。
直接作为子模块引用

有些库并不是通过 find_package 命令来引用的，而是直接将其作为子模块引入项目中，例如

1. add_subdirectory(spdlog)
2. target_link_libraries(myapp PUBLIC spdlog)

复制代码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！