面向 C++ 的现代 CMake 教程（一）(1)

序言

打造顶级软件并非易事。开发者在网上研究这一主题时，常常遇到的问题是如何判断哪些建议是更新的，哪些方法已经被更 fresh、更好的实践所超越。与此同时，大多数资源对这个过程的解释是混乱的，没有适当的背景、上下文和结构。

现代 CMake for C++ 是一本端到端的指南，提供了更简单的体验，因为它全面地处理了 C++解决方案的构建。它教会您如何在 CMake 项目中使用 CMake，并展示使其可维护、优雅和干净的原因。它引导您通过许多项目中出现的复杂任务的自动化，包括构建、测试和打包。

本书将指导您如何形成源目录，以及如何构建目标和包。随着您的进展，您将学习如何编译和链接可执行文件和库，这些过程是如何详细工作的，以及如何优化所有步骤以获得最佳结果。您还将了解如何将外部依赖项添加到项目中：第三方库、测试框架、程序分析工具和文档生成器。最后，您将探索如何为内部和外部目的导出、安装和打包您的解决方案。

完成本书后，您将能够在专业水平上自信地使用 CMake。

本书适合谁阅读

学习 C++语言往往不足以让你为交付项目到最高标准做好准备。如果你有兴趣成为一名专业的构建工程师，一个更好的软件开发者，或者简单地说，想精通 CMake，如果你想了解项目是如何组合在一起的以及为什么这样，如果你正在从不同的构建环境中过渡，或者如果你对从零开始学习现代 CMake 感兴趣，那么这本书适合你。

本书涵盖内容

第一章，CMake 的初步步骤，涵盖了如何安装和使用 CMake 的命令行，以及构成项目的文件。

第二章，CMake 语言，提供了关键代码信息：注释、命令调用和参数、变量、列表和控制结构。

第三章，设置您的第一个 CMake 项目，介绍了项目的基本配置、所需的 CMake 版本、项目元数据和文件结构，以及工具链设置。

第四章，与目标工作，介绍了逻辑构建目标，这些目标为可执行文件和库生成工件。

第五章，使用 CMake 编译 C++源代码，解释了编译过程的细节以及如何在 CMake 项目中控制编译过程。

第六章，使用 CMake 链接，提供了关于链接、静态和共享库的一般信息。本章还解释了如何结构化一个项目，以便它可以被测试。

第七章，使用 CMake 管理依赖项，解释了现代 CMake 中可用的依赖管理方法。

第八章，测试框架，描述了如何将最流行的测试框架添加到您的项目中，以及如何使用 CMake 工具集中的 CTest 工具。

第九章，程序分析工具，介绍了如何在您的项目中执行自动格式化，以及进行静态和动态分析。

第十章，生成文档，解释了如何使用 Doxygen 直接从 C++源代码生成用户手册。

第十一章，安装和打包，展示了如何将您的项目准备成在其他项目中使用或在系统上安装。我们还将看到 CPack 工具的解释。

第十二章，创建你的专业项目，介绍了如何将迄今为止你所获得的所有知识整合成一个完全形成的项目。

附录：杂项命令，提供最流行命令的快速参考：string()、list()、file() 和 math()。

为了充分利用本书

本书假设您对 C++和类 Unix 系统有基本的熟悉度。虽然这不是一个严格的要求，但熟悉这些内容将有助于您完全理解本书中的示例。

本书针对 CMake 3.20，但描述的大多数技术应该从 CMake 3.15 起就可以工作（在之后添加的功能通常会 highlighted）。

所有示例已在安装以下包的 Debian 上进行测试：

clang-format clang-tidy cppcheck doxygen g++ gawk git graphviz lcov libpqxx-dev libprotobuf-dev make pkg-config protobuf-compiler tree valgrind vim wget

为了体验相同的环境，建议使用如第一章所解释的 Docker 镜像。

如果你使用的是本书的数字版，我们建议你亲自输入代码或从本书的 GitHub 仓库（下一节中有链接）访问代码。这样做可以帮助你避免因复制和粘贴代码而可能出现的任何潜在错误。

下载示例代码文件

您可以从 GitHub 下载本书的示例代码文件，地址为github.com/PacktPublishing/Modern-CMake-for-Cpp。如果代码有更新，它将在 GitHub 仓库中更新。

我们还有其他丰富的书籍和视频目录中的代码包，可在github.com/PacktPublishing/找到。去看看吧！

下载彩色图像

我们还提供了一个 PDF 文件，其中包含本书中使用的屏幕截图和图表的彩色图像。您可以通过此链接下载： static.packt-cdn.com/downloads/9781801070058_ColorImages.pdf。

本书中使用了以下约定：

本书中使用了多种文本约定。

文本中的代码：表示文本中的代码单词、数据库表名、文件夹名、文件名、文件扩展名、路径名、假 URL、用户输入和 Twitter 处理。以下是一个示例：“选择Debug、Release、MinSizeRel或RelWithDebInfo并按如下方式指定。”

代码块如下所示：

cmake_minimum_required(VERSION 3.20)
project(Hello)
add_executable(Hello hello.cpp)

当我们要引起您对代码块中特定部分的关注时，相关行或项目以粗体显示：

cmake_minimum_required(VERSION 3.20)
project(app)
message("Top level CMakeLists.txt")
add_subdirectory(api)

任何命令行输入或输出如下所示：

cmake --build <dir> --parallel [<number-of-jobs>]
cmake --build <dir> -j [<number-of-jobs>]

粗体：表示新术语、重要单词或您在屏幕上看到的单词。例如，菜单或对话框中的单词以粗体显示。以下是一个示例：“如果其他方法都失败了，我们需要使用大炮，总有跟踪模式。”

提示或重要说明

文本中代码如下所示。

第一部分：介绍 CMake

打好基础对于理解更高级的内容和避免愚蠢的错误至关重要。大多数 CMake 用户在这里会遇到麻烦：没有坚实的基础，很难达到正确的结果。难怪会这样。跳过入门材料，直接进入实际行动并快速完成任务是很有诱惑力的。我们在本节中解释了 CMake 的核心主题，并拼凑了几行代码来展示最简单的项目看起来是什么样子，以解决这两个问题。

为了构建恰当的思维背景，我们将解释 CMake 究竟是什么以及它是如何工作的，还会介绍命令行的样子。我们会讨论不同的构建阶段，并学习用于生成构建系统的语言。我们还将讨论 CMake 项目：它们包含哪些文件，如何处理它们的目录结构，以及我们将探索它们的主要配置。

本部分包括以下章节：

• 第一章，《CMake 的初步步骤》
  
• 第二章，《CMake 语言》
  
• 第三章，《设置你的第一个 CMake 项目》
  

第一章：CMake 的初步步骤

将源代码转换成运行中的应用程序有一种神奇的感觉。这种神奇不仅仅在于效果本身，即我们设计并使其实际运行的机制，而且在于将想法付诸实践的过程或行为。

作为程序员，我们按照以下循环工作：设计、编码和测试。我们发明变更，我们用编译器能理解的言语来阐述它们，然后我们检查它们是否如预期那样工作。为了从我们的源代码创建一个适当、高质量的程序，我们需要精心执行重复性、易出错的任务：调用正确的命令，检查语法，链接二进制文件，运行测试，报告问题，等等。

每次都记住每个步骤需要付出很大的努力。相反，我们希望专注于实际的编程，并将其他所有任务委派给自动化工具。理想情况下，这个过程将从我们更改代码后立即开始，只需按一个按钮。它会智能、快速、可扩展，并且在不同的操作系统和环境中以相同的方式工作。它会被多种集成开发环境（IDEs）支持，同时也会被持续集成（CI）管道支持，在我们向共享仓库提交更改后测试我们的软件。

CMake 是许多需求的答案；然而，要正确配置和使用它需要一些工作。这不是因为 CMake 不必要的复杂，而是因为我们这里处理的主题就是这样。不要担心。我们将非常有条理地进行整个学习过程；在您意识到之前，您将已经成为一个建筑大师。

我知道您渴望开始编写自己的 CMake 项目，我赞赏您的热情。由于您的项目主要面向用户（包括您自己），您理解这一观点也很重要。

那么，让我们从这一点开始：成为 CMake 的高级用户。我们会先了解一些基础知识：这个工具是什么，它的工作原理是什么，以及如何安装它。然后，我们将深入探讨命令行和操作模式。最后，我们将总结项目中不同文件的目的，并解释如何在不下创建项目的情况下使用 CMake。

在本章中，我们将涵盖以下主要主题：

• 理解基础知识
  
• 在不同平台上安装 CMake
  
• 掌握命令行
  
• 导航项目文件
  
• 发现脚本和模块
  

技术要求

您可以在 GitHub 上找到本章中存在的代码文件：github.com/PacktPublishing/Modern-CMake-for-Cpp/tree/main/examples/chapter01。

为了构建本书中提供的示例，始终使用建议的命令：

cmake -B <build tree> -S <source tree>
cmake --build <build tree>

请确保将占位符<build tree>和<source tree>替换为适当的路径。作为提醒：build tree是目标/输出目录的路径，source tree是源代码所在的位置。

理解基础知识

编译 C++源代码似乎是一个相当直接的过程。让我们以一个小型程序为例，比如经典的hello.cpp应用：

chapter-01/01-hello/hello.cpp

#include <iostream>
int main() {
  std::cout << "Hello World!" << std::endl;
  return 0;
}

现在，要获得可执行文件，我们只需要运行一个命令。我们通过将文件名作为参数传递给编译器来调用它：

$ g++ hello.cpp -o a.out

我们的代码是正确的，所以编译器将默默生成一个可执行的二进制文件，我们的机器可以理解。我们可以通过调用它的名字来运行它：

$ ./a.out
Hello World!
$

然而，随着我们的项目增长，你会很快理解将所有内容放在一个文件中 simply not possible。良好的代码实践建议文件应保持小且结构良好。手动编译每个文件可能是一个繁琐且脆弱的过程。一定有更好的方法。

什么是 CMake？

假设我们通过编写一个脚本来自动化构建，该脚本遍历我们的项目树并编译所有内容。为了避免不必要的编译，我们的脚本将检测源代码是否自上次运行（脚本）以来已被修改。现在，我们想要一种方便地管理传递给每个文件编译器的参数的方法——最好是基于可配置标准来完成。此外，我们的脚本应知道如何链接所有编译文件到一个二进制文件中，或者更好，构建整个解决方案，可以被复用并作为更大项目的模块。

我们添加的功能越多，我们得到一个完整的解决方案的机会就越大。软件构建是一个非常多样化的过程，可以涵盖多个不同的方面：

• 编译可执行文件和库
  
• 管理依赖项
  
• 测试
  
• 安装
  
• 打包
  
• 生成文档
  
• 再测试一下
  

要创建一个真正模块化且强大的 C++构建应用程序需要很长时间，而且确实做到了。Bill Hoffman 在 Kitware 实现了 CMake 的第一个版本，至今已有 20 多年。正如你可能已经猜到的，它非常成功。它现在有很多功能和社区支持。今天，CMake 正在积极开发中，并已成为 C 和 C++程序员的行业标准。

自动化构建代码的问题比 CMake 要早得多，所以自然而然，有很多选择：Make、Autotools、SCons、Ninja、Premake 等等。但为什么 CMake 能占据上风呢？

关于 CMake，有几件事情我觉得（主观地）很重要：

• 它专注于支持现代编译器和工具链。
  
• CMake 确实是跨平台的——它支持为 Windows、Linux、macOS 和 Cygwin 构建。
  
• 它为流行的 IDE 生成项目文件：Microsoft Visual Studio、Xcode 和 Eclipse CDT。此外，它还是其他项目的模型，如 CLion。
  
• CMake 在恰到好处的抽象级别上操作——它允许你将文件分组到可重用的目标和项目中。
  
• 有大量使用 CMake 构建的项目，它们提供了一种轻松将它们包含在你项目中的方法。
  
• CMake 将测试、打包和安装视为构建过程的固有部分。
  
• 旧的、未使用的特性会被弃用，以保持 CMake 的轻量级。
  

CMake 为整个平台提供了一致、简化的体验。无论你是使用 IDE 构建软件，还是直接从命令行构建，重要的是它还负责后构建阶段。你的持续集成/持续部署（CI/CD）流水线可以轻松使用相同的 CMake 配置和构建项目，即使所有前面的环境都不同。

它是如何工作的？

你可能还以为 CMake 是一个工具，在一端读取源代码，在另一端生成二进制文件——虽然从原则上讲这是正确的，但这并不是全部。

CMake 本身不能构建任何东西——它依赖于系统中的其他工具来执行实际的编译、链接等任务。你可以把它看作是你构建过程的协调者：它知道需要做哪些步骤，最终目标是什么，以及如何找到合适的工人和材料。

这个过程分为三个阶段：

• 配置阶段
  
• 生成
  
• 构建
  

配置阶段

这个阶段是关于读取存储在称为源树的目录中的项目详细信息，并为生成阶段准备输出目录或构建树。

CMake 首先创建一个空的构建树，并收集有关它正在工作的环境的详细信息，例如架构、可用的编译器、链接器和归档器。此外，它检查一个简单的测试程序是否可以正确编译。

接下来，解析并执行CMakeLists.txt项目配置文件（是的，CMake 项目是用 CMake 的编程语言配置的）。这个文件是 CMake 项目的最小配置（源文件可以在以后添加）。它告诉 CMake 关于项目结构、目标和依赖项（库和其他 CMake 包）。在这个过程中，CMake 将在构建树中存储收集的信息，如系统详细信息、项目配置、日志和临时文件，供下一步使用。特别是，创建了一个CMakeCache.txt文件来存储更稳定的变量（如编译器和其他工具的路径），以节省下一次配置的时间。

生成阶段

在阅读项目配置后，CMake 将为它正在工作的确切环境生成一个构建系统。构建系统只是为其他构建工具（例如，为 GNU Make 的 Makefile 或为 Ninja 和 Visual Studio 的 IDE 项目文件）定制的配置文件。在这个阶段，CMake 仍然可以通过评估生成器表达式来对构建配置进行一些最后的润色。

注意

生成阶段在配置阶段自动执行后执行。因此，本书和其他资源在提到“配置”或“生成”构建系统时，通常会提到这两个阶段。要显式运行 just the 配置阶段，你可以使用cmake-gui工具。

构建阶段

为了生成我们项目中所指定的最终工件，我们必须运行适当的构建工具。这可以直接通过 IDE 调用，或者使用 CMake 命令。反过来，这些构建工具将执行步骤，使用编译器、链接器、静态和动态分析工具、测试框架、报告工具以及你能想到的任何其他工具来生成目标。

这个解决方案的优点在于能够根据需要为每个平台生成构建系统，只需一个配置（即，相同的项目文件）：

[外链图片转存中…(img-gYqA6UYM-1716544491727)]

](https://gitee.com/OpenDocCN/freelearn-c-cpp-pt2-zh/raw/master/docs/mdn-cmk-cpp/img/Figure_1.1_B17205.jpg)

图 1.1 – CMake 的阶段

你们还记得我们在理解基本内容部分提到的hello.cpp应用程序吗？CMake 让构建它变得非常简单。我们需要的只是一个位于源代码旁边的CMakeLists.txt文件和两个简单的命令cmake -B buildtree和cmake --build buildtree，如下所示：

chapter01/01-hello/CMakeLists.txt：用 CMake 语言编写的世界

cmake_minimum_required(VERSION 3.20)
project(Hello)
add_executable(Hello hello.cpp)

这是来自 Dockerized Linux 系统的输出（请注意，我们将在在不同的平台上安装 CMake部分讨论 Docker）：

root@5f81fe44c9bd:/root/examples/chapter01/01-hello# cmake -B buildtree.
-- The C compiler identification is GNU 9.3.0
-- The CXX compiler identification is GNU 9.3.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done
-- Generating done
-- Build files have been written to: /root/examples/chapter01/01-hello/buildtree
root@5f81fe44c9bd:/root/examples/chapter01/01-hello# cmake --build buildtree/
Scanning dependencies of target Hello
[ 50%] Building CXX object CMakeFiles/Hello.dir/hello.cpp.o
[100%] Linking CXX executable Hello
[100%] Built target Hello

现在只剩下运行它了：

root@68c249f65ce2:~# ./buildtree/Hello
Hello World!

在这里，我们生成了一个存储在buildtree目录中的构建系统。接着，我们执行了构建阶段，生成了一个我们能够运行的最终二进制文件。

现在你知道最终结果长什么样了，我相信你会有很多问题：这个过程的前提条件是什么？这些命令意味着什么？为什么我们需要两个？我如何编写自己的项目文件？不要担心——这些问题将在接下来的章节中得到解答。

获取帮助

本书将为您提供与当前版本的 CMake（撰写本书时为 3.20 版）最相关的最重要的信息。为了给您提供最好的建议，我明确避免使用任何已弃用和不推荐使用的功能。我强烈建议至少使用版本 3.15，这个版本被认为是“现代 CMake”。如果您需要更多信息，您可以在cmake.org/cmake/help/找到最新的完整文档。

在不同的平台上安装 CMake

CMake 是一个用 C++编写的跨平台、开源软件。这意味着你当然可以自己编译它；然而，最有可能的情况是，你不需要这么做。这是因为预编译的二进制文件可以在官方网页cmake.org/download/上供你下载。

基于 Unix 的系统可以直接从命令行提供准备安装的包。

注意

请记住，CMake 不附带编译器。如果你的系统还没有安装它们，你需要在使用 CMake 之前提供它们。确保将它们的执行文件路径添加到PATH环境变量中，这样 CMake 才能找到它们。

为了避免在阅读本书时解决工具和依赖问题，我建议选择第一种安装方法：Docker。

让我们来看看可以在哪些环境中使用 CMake。

Docker

Docker (www.docker.com/) 是一个跨平台的工具，提供操作系统级别的虚拟化，允许应用程序以完整的包形式运输，这些包被称为容器。这些都是自给自足的捆绑包，包含了一个软件以及它所有的库、依赖项和运行它所需的工具。Docker 在其轻量级环境中执行其容器，彼此之间是隔离的。

这个概念使得分享整个工具链变得极其方便，这对于给定的过程是必要的，已经配置好并准备好使用。我无法强调当你不需要担心微小的环境差异时事情变得有多简单。

Docker 平台有一个公共容器镜像仓库，registry.hub.docker.com/，提供了数百万个准备使用的镜像。

为了方便起见，我发布了两个 Docker 仓库：

• swidzinski/cmake:toolchain：这个包含了构建 CMake 所需的精心挑选的工具和依赖项。
  
• swidzinski/cmake:examples：这个包含了前面的工具链以及本书中的所有项目和示例。
  

第一个选项是为那些只想使用一个空白镜像来构建自己项目的读者准备的，第二个选项是为在章节中进行实例实践准备的。

你可以通过遵循 Docker 官方文档中的说明来安装 Docker（请参考docs.docker.com/get-docker）。然后，在你的终端中执行以下命令来下载镜像并启动容器：

$ docker pull swidzinski/cmake:examples
$ docker run -it swidzinski/cmake:examples
root@b55e271a85b2:root@b55e271a85b2:#

请注意，所有示例都可以在匹配此格式的目录中找到：/root/examples/``examples/chapter-<N>/<M>-<title>。

Windows

在 Windows 上的安装很简单——只需下载 32 位或 64 位的版本。你可以选择一个便携式 ZIP 或 MSI 包用于 Windows 安装程序。

使用 ZIP 包，你将不得不将 CMake 二进制目录添加到PATH环境变量中，这样你才能在任何目录中使用它，而不会出现错误：

'cmake' is not recognized as an internal or external command, operable program or batch file.

如果你喜欢方便，可以直接使用 MSI 安装程序：

[外链图片转存中…(img-H18778bs-1716544491728)]

图 1.2 – 安装向导可以为你设置 PATH 环境变量

如我前面提到的，这是开源软件，所以自己构建 CMake 是可能的。然而，首先，你需要在你的系统上获取 CMake 的二进制副本。那么，如果你有自己的构建工具，为什么还要使用其他的呢？这种场景是 CMake 贡献者用来生成新版本的。

在 Windows 上，我们还需要一个构建工具来完成由 CMake 启动的构建过程。这里的一个流行选择是 Visual Studio，其社区版可从微软网站免费获得：visualstudio.microsoft.com/downloads/。

Linux

在 Linux 上获取 CMake 与获取任何其他流行软件包相同。只需使用命令行的包管理器即可。软件包通常会保持更新，包含相对较新的版本。然而，如果你想要最新版本，你可以从网站上下载安装脚本：

适用于 Linux x86_64 的脚本

$ wget -O - https://github.com/Kitware/CMake/releases/download/v3.20.0/cmake-3.20.0-linux-x86_64.sh | bash

适用于 Linux aarch64 的脚本

$ wget -O - https://github.com/Kitware/CMake/releases/download/v3.20.0/cmake-3.20.0-Linux-aarch64.sh | bash

适用于 Debian/Ubuntu 的软件包

$ sudo apt-get install cmake

适用于 Red Hat 的软件包

$ yum install cmake

macOS

这个平台也得到了 CMake 开发者的强烈支持。最流行的安装方式是通过 MacPorts：

$ sudo port install cmake

另外，你可以使用 Homebrew：

$ brew install cmake

从源代码构建

如果其他方法都失败了——或者如果你在一个特殊的平台上——从官方网站下载源代码并自己编译它：

$ wget https://github.com/Kitware/CMake/releases/download/v3.20.0/cmake-3.20.0.tar.gz
$ tar xzf cmake-3.20.0.tar.gz
$ cd cmake-3.20.0
$ ./bootstrap
$ make
$ make install

从源代码构建相对较慢，需要更多步骤。然而，通过这种方式，你可以保证使用最新版本的 CMake。这在与 Linux 上可用的软件包相比较时尤为明显：系统版本越旧，更新越少。

既然我们已经轻松安装了 CMake，那就让我们学习如何使用它吧！

精通命令行

本书的大部分内容将教你如何为你的用户准备 CMake 项目。为了满足他们的需求，我们需要彻底了解用户在不同场景中如何与 CMake 互动。这将允许你测试项目文件，并确保它们正确运行。

CMake 是一组工具的家族，包括五个可执行文件：

• cmake：这是主要的可执行文件，用于配置、生成和构建项目。
  
• ctest：这个程序用于运行和报告测试结果。
  
• cpack：这个程序用于生成安装程序和源代码包。
  
• cmake-gui：这是围绕cmake的图形界面。
  
• ccmake：这是基于控制台的图形界面围绕cmake。
  

CMake

这个二进制文件提供了一些操作模式（也称为动作）：

• 生成项目构建系统
  
• 构建项目
  
• 安装项目
  
• 运行脚本
  
• 运行命令行工具
  
• 获取帮助
  

生成项目构建系统

安装项目是我们构建项目所需的第一步。以下是执行 CMake 构建操作的几种方式：

生成模式的语法

cmake [<options>] -S <path-to-source> -B <path-to-build>
cmake [<options>] <path-to-source>
cmake [<options>] <path-to-existing-build>

我们将在接下来的部分讨论这些选项。现在，让我们专注于选择正确的命令形式。CMake 的一个重要特性是支持离线构建或在单独的目录中生成工件。与 GNU Make 等工具相比，这确保了源代码目录中不会包含任何与构建相关的文件，并避免了使用-S选项后跟生成构建系统的目录路径的污染：

cmake -S ./project -B ./build

前面命令将在./build目录中（如果缺失则创建）生成一个构建系统，该构建系统来源于./project目录中的源代码。

我们可以省略一个参数，cmake会“猜测”我们打算使用当前目录。但是，要小心。省略两个参数将会得到一个源代码构建，这将非常混乱。

不推荐

<directory>: it will use the cached path to the sources and rebuild from there. Since we often invoke the same commands from the Terminal command history, we might get into trouble here: before using this form, always check whether your shell is currently working in the right directory.

示例

在当前目录中构建，但源代码从上一级目录获取（注意-S是可选的）：

cmake -S ..

在./build目录中构建，并使用当前目录中的源代码：

cmake -B build

面向 C++ 的现代 CMake 教程（一）(2)https://developer.aliyun.com/article/1526963