1.4k star 项目 CMakeTutorial 阅读和点评

1.4k star 项目 CMakeTutorial 阅读和点评

0. 概要

在 github 搜索关键字 CMake, 靠前的结果中第一个中文仓库是 https://github.com/BrightXiaoHan/CMakeTutorial , 目前（2024.06.18) 有 1.2k， 今天阅读和点评这个项目。

相比于先前分析过的仓库，BrightXiaoHan 的 CMakeTutorial 仓库的优点：

• 使用中文讲解，直白易懂
• 提供了网页，可以在线阅读:
  https://brightxiaohan.github.io/CMakeTutorial/

缺点：

• 只在 Linux 下实践， 没有 Windows 支持
• 样例覆盖范围不够广泛, 只有6个目录

➜  CMakeTutorial git:(master) tree -L 1
.
├── CUDA
├── FindPackage
├── ImportExternalProject
├── Installation
├── LICENSE
├── PackageManage
├── PythonExtention
├── README.md
└── _config.yml

6 directories, 3 files

包含了6个目录，每个目录里是一个特定场景案例。 覆盖的场景显然不会太全, 不过每个提供的目录都还算精良, 下面逐一阅读点评。

1. CUDA 目录

作者提到从 cmake 3.9 开始， 原生支持了 CUDA C/C++. 也就是可以直接在 project() 中指定语言为 CUDA, 以及添加 .cu 文件到 target 中:

project(CUDA_MAT_MUL LANGUAGES CXX CUDA)
add_library(cudaMatMul cudaMatMul.cu cudaMatMul.h)
target_compile_features(cudaMatMul PUBLIC cxx_std_11)

比较遗憾的是，提供的引入 cublas 库的方式比较繁琐, 是参照了 CLblast - FindcuBLAS.cmake ， 这仍然原本是包管理器应该做的事情， 转嫁负担到普通用户了。 此外， 提供的 FindcuBLAS.cmake 没有支持 Windows, 跨平台方面还需要改善, 不能直接拿去用。

在提供的示例代码方面， 作者比较用心了， 提供的是 CUDA 方面的入门例子： 矩阵乘法。 相比于简单的打印 hello world， MatMul 的代码更贴合实际场景， 体现了 C/C++ 和 cuda 在同一个文件中混合编译的用法。

2. FindPackage 目录

本节内容仍然是只能在 Linux 下使用， windows/macOS 没有适配， 是一个不足。

作者提到了 path_to_your_cmake/share/cmake-/Modules 这个目录， 是 cmake 安装后提供的用于 find_package() 的包说明文件， 也就是众多的 Findxxx.cmake 文件、相关文件、子目录等。 这很难得， 前面看的 Cmake 高赞项目都没提到这点。

具体的案例， 作者使用了 curl 库为例子， 用 find_package 查询：

find_package(CURL)
add_executable(curltest curltest.cc)
if(CURL_FOUND)
    target_include_directories(clib PRIVATE ${CURL_INCLUDE_DIR})
    target_link_libraries(curltest ${CURL_LIBRARY})
else(CURL_FOUND)
    message(FATAL_ERROR ”CURL library not found”)
endif(CURL_FOUND)

不过， 上述代码显然是不够 modern， else(CURL_FOUND) 和 endif(CURL_FOUND) 可以把括号里留空。

作者还给出了通过自行配置, 让 find_package() 支持了 glog 库的导入。作者这里想表达的含义是， cmake 安装路径下的 share/cmake-/Modules 目录有时候没能覆盖你想找的库， 此时从源码编译你要找的库， 比如 glog， 并且假设你要找的库也是基于 cmake 构建的， 那么它（大概率）提供了 find_package() 的支持。

不过， glog 算是支持还算好的， 这种 find_package 支持， 全靠运气， 有些开源库作者就是没有写 cmake， 这时候需要另外想办法。这种情况可以细分， 对于是自己编写的代码， 比如基于 makefile 构建的库 libAdd, 作者提供了编写 FindAdd.cmake 的步骤。 这些步骤是可以用的， 但是只覆盖了 Linux， 并且目前（2024年）比较不推荐 FindAdd.cmake , 而是推荐 AddConfig.cmake 文件。这一节的内容稍微有点落伍了。

3. Installation 目录

这个目录介绍的是， 把自己编写的一个库 mymath，添加“安装”功能， 能安装它的头文件和库文件。 mymath 的代码简单而不失实用性， 是求整数和浮点数的和。 相比于 CMake 官方的 Tutorial 中求 sqrt 的代码， 对普通人更加友好。 介绍库的安装， 重点在于安装， 而不是把示例库本身的 cpp 代码搞得有点复杂。

这个例子写的还行：

install(TARGETS mymath
        EXPORT MyLibTargets
        LIBRARY DESTINATION lib  # 动态库安装路径
        ARCHIVE DESTINATION lib  # 静态库安装路径
        RUNTIME DESTINATION bin  # 可执行文件安装路径
        PUBLIC_HEADER DESTINATION include  # 头文件安装路径
)

几个不太行的地方：

1. 关于默认安装位置， 可能4年前作者用的 CMake 版本， 在 windows 上是安装到 c:/Program Files/${PROJECT_NAME}， 也可能作者没有具体尝试仅仅是抄写了官方文档， 其实这个路径应该是 c:/Program Files (x86)/${PROJECT_NAME}.

2. set_target_properties(mymath PROPERTIES PUBLIC_HEADER ${CMAKE_SOURCE_DIR}/include/mymath.h) 这句， 多余的。

3. 关于 MyMathConfigVersion.cmake 和 MyMathConfig.cmake.in 文件：作者应该是仔细看了 CMake 官方文档， 整体看没有大问题。 主要的问题在于， 这东西写起来太繁琐（CMake的设计的问题）。 实际上如果是打算写一个包管理器， 那应该自动生成 MyMathConfig.cmake 文件， 尽可能减少手写那些又重复、又难写、又容易出错的写法， 例如：

include(CMakePackageConfigHelpers)
write_basic_package_version_file(
        MyMathConfigVersion.cmake
        VERSION ${PACKAGE_VERSION}
        COMPATIBILITY AnyNewerVersion  # 表示该函数库向下兼容
        )

4. PackageManage 目录

这个目录应该改名为 PackageManagement. 作者给出了两个包管理器的示例说明:

• vcpkg
• anaconda

具体到 CMakeLists.txt 文件， 和没有使用包管理器的写法是一样的。 可以说作者应该没有很深入的使用 vcpkg， anaconda 的话个人不太了解， 不评价。 对于 vcpkg， 在2024年显然应该补充 override 和 builtin-baseline 的设置例子， 因为这是锁定包的版本， 而不能锁定包版本的管理器显然都是不合格的。

这个目录其实几乎没用， 建议读者直接移步 vcpkg 或 conan 官方。

5. PythonExtension 目录

这节是 Python 扩展的用法， 作者使用了 Python 自带的头文件，而不是基于 Python 头文件的封装过的库如 PyBind11 等。

使用的具体代码， 是 Eigen 库的矩阵类， 封装了 random, ones, zeros 等函数。

cmake_minimum_required (VERSION 3.0)
project (PybindMatrix)

find_package (Eigen3 REQUIRED NO_MODULE)
find_package(PythonLibs REQUIRED)

include_directories(${PYTHON_INCLUDE_DIRS})
add_library(matrix python_matrix.cc)
target_compile_features(matrix PRIVATE cxx_std_11)
target_link_libraries (matrix ${PYTHON_LIBRARIES} Eigen3::Eigen)

这个例子其实有一定的实用价值， Eigen 自身有较好的计算性能， 如果是基于 Eigen 实现了某些功能， 或者打算用 Python 快速做一些实现， 基于已有的工程公共代码， 而公共代码是基于 Eigen 写的， 那么这个例子可以作为起始参考代码，能快速添加矩阵相关的计算。 当然了，抛开 C++ Eigen 库， 也可以用 python 的 pyquaternion 和 numpy, scipy 库， 但是那样的话， python 和 c++ 的库在二进制对齐方面可能就容易出岔子。

对于 Python 库的构建， 目前（2024年）看起来用 project.toml 比 setup.py 更好， 这是一个改进点。

6. ImportExternalProject 目录

这个目录介绍如何引入外部项目。 其实这仍然是包管理范畴的事情， 只不过现在可以添加的不一定是二进制库+头文件的传统“开发包”， 也可以是 header-only 库（其实就是源代码）， 也可以是 头文件+源文件 的源码工程。

具体说来， 作者使用了 FetchContent， 这在网络良好的条件下确实是 OK 的：

# 添加第三方依赖包
include(FetchContent)
# FetchContent_MakeAvailable was not added until CMake 3.14
if(${CMAKE_VERSION} VERSION_LESS 3.14)
    include(add_FetchContent_MakeAvailable.cmake)
endif()

set(SPDLOG_GIT_TAG  v1.4.1)  # 指定版本
set(SPDLOG_GIT_URL  https://github.com/gabime/spdlog.git)  # 指定git仓库地址

FetchContent_Declare(
  spdlog
  GIT_REPOSITORY    ${SPDLOG_GIT_URL}
  GIT_TAG           ${SPDLOG_GIT_TAG}
)

FetchContent_MakeAvailable(spdlog)

但显然 FetchContent 是不够的， 作者这个目录也只能当玩具， 我认为需要补充的是：

• add_subdirectory() 方式，使用外层目录下的子目录， 例如 fmtlib
• add_subdirectory() 方式， 使用子目录或外层目录的子目录， 目录里的 CMakeLists.txt 中， 通过定义 IMPORTED 库来提供外部使用

总结

这个 1.2k star 的项目 CMakeTutorial ， 在提供的内容中，CUDA 和 PythonExtension 在多年之后仍有较好的实用价值， Installation、 PackageManage, FindPackage, ImportExternalProject 则是凑合使用、 但根因在于 CMake 自身的设计， 初学者可以大概看看，但应寻求更好做法。 考虑到是中文写成， 易读性还是相当可以的。