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 目录

1.4k star 项目 CMakeTutorial 阅读和点评-LMLPHP

作者提到从 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-<version>/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  # 头文件安装路径
)

几个不太行的地方：

关于默认安装位置，可能4年前作者用的 CMake 版本，在 windows 上是安装到 c:/Program Files/${PROJECT_NAME}，也可能作者没有具体尝试仅仅是抄写了官方文档，其实这个路径应该是 c:/Program Files (x86)/${PROJECT_NAME}.
set_target_properties(mymath PROPERTIES PUBLIC_HEADER ${CMAKE_SOURCE_DIR}/include/mymath.h) 这句，多余的。
关于 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 自身的设计，初学者可以大概看看，但应寻求更好做法。考虑到是中文写成，易读性还是相当可以的。

baiyu33