Cmake用户交互指南

文章目录

[一. 介绍](#一. 介绍)
- [1. 命令行cmake工具](#1. 命令行cmake工具)
- [2. cmake gui工具](#2. cmake gui工具)
[二. 生成构建系统](#二. 生成构建系统)
- [1. 命令行环境](#1. 命令行环境)
- [2. 命令行-G选项](#2. 命令行-G选项)
- [3. 在cmake gui中选择生成器](#3. 在cmake gui中选择生成器)
[三. 设置生成变量](#三. 设置生成变量)
- [1. 在命令行上设置变量](#1. 在命令行上设置变量)
- [2. 使用cmake gui设置变量](#2. 使用cmake gui设置变量)
- [3. CMake缓存](#3. CMake缓存)
[四. 预设](#四. 预设)
- [1. 在命令行上使用预设](#1. 在命令行上使用预设)
- [2. 在cmake gui中使用预设](#2. 在cmake gui中使用预设)
[五. 调用Buildsystem](#五. 调用Buildsystem)
- [1. 选择目标](#1. 选择目标)
- [2. 指定生成程序](#2. 指定生成程序)
[六. 软件安装](#六. 软件安装)
[七. 运行测试](#七. 运行测试)

一. 介绍

如果某个软件是基于CMake的构建系统来为其提供其它软件库的来源，则这个软件的使用者必须运行CMake用户交互工具来构建该软件。

1. 命令行cmake工具

cmake的一个简单但典型的用法是创建一个构建目录并在那里调用cmake：

bash 复制代码

cd some_software-1.4.2
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/opt/the/prefix
cmake --build .
cmake --build . --target install

建议在源代码的单独文件夹(build文件夹)中进行构建，因为这样可以保持源代码文件夹的原始状态，允许使用多个工具链构建单个源代码，并且只需删除构建文件夹(build文件夹)即可轻松清除不需要的构建项目。

CMake工具可能会报告针对软件提供商而非软件消费者的警告。此类警告以"此警告适用于项目开发人员"结尾。用户可以通过将-Wno-dev标志传递给cmake来禁用此类警告。

2. cmake gui工具

更习惯于GUI界面的用户可以使用cmake-GUI工具来调用cmake并生成构建系统。

首先，必须填充源代码目录和生成的二进制保存目录。总是建议对源代码和构建目录使用不同的文件夹。

二. 生成构建系统

有几个用户界面工具可以用来从CMake文件生成构建系统。ccmake和cmake gui工具指导用户设置各种必要的选项。可以调用cmake工具来指定命令行上的选项。本说明描述了可以使用任何用户界面工具设置的选项，尽管每个工具的选项设置模式不同。

1. 命令行环境

当使用命令行构建系统（如Makefiles或Ninja）调用cmake时，有必要使用正确的构建环境来确保构建工具可用。CMake必须能够根据需要找到合适的构建工具、编译器、链接器和其他工具。

在Linux系统上，适当的工具通常在系统范围内的位置提供，并且可以通过系统包管理器轻松安装。也可以使用用户提供的或安装在非默认位置的其他工具链。

在交叉编译时，一些平台可能需要设置环境变量，或者可能提供脚本来设置环境。

Visual Studio提供了多个命令提示符和vcvarsall.bat脚本，用于为命令行构建系统设置正确的环境。虽然在使用Visual Studio生成器时不一定需要使用相应的命令行环境，但这样做没有任何缺点。

使用Xcode时，可以有多个Xcode版本i

2. 命令行-G选项

CMake默认情况下会根据平台选择生成器。通常，默认生成器足以允许用户继续构建软件。

用户可以使用-G选项覆盖默认生成器：

bash 复制代码

cmake .. -G Ninja

cmake --help的输出包括可供用户选择的生成器列表。请注意，生成器名称区分大小写。

在类Unix系统（包括Mac OS X）上，默认使用Unix Makefiles生成器。该生成器的变体也可以在Windows上的各种环境中使用，例如NMake Makefiles和MinGW Makefiles生成器。这些生成器生成一个Makefile变体，可以使用make、gmake、nmake或类似工具执行。有关目标环境和工具的更多信息，请参阅各个生成器文档。
Ninja生成器可在所有主要平台上使用。ninja是一个构建工具，在用例中与make类似，但侧重于性能和效率。
在Windows上，cmake可用于为Visual Studio IDE生成解决方案。Visual Studio版本可以由IDE的产品名称指定，其中包括四位数的年份。别名是为Visual Studio版本提供的其他方式
bash 复制代码
```
cmake .. -G "Visual Studio 2019"
cmake .. -G "Visual Studio 16"
cmake .. -G "Visual Studio 16 2019"
```
Visual Studio生成器可以针对不同的体系结构。可以使用-A选项指定目标系统结构：
bash 复制代码
```
cmake .. -G "Visual Studio 2019" -A x64
cmake .. -G "Visual Studio 16" -A ARM
cmake .. -G "Visual Studio 16 2019" -A ARM64
```
在Apple上，Xcode生成器可以用于为Xcode IDE生成项目文件。

一些IDE，如KDevelop4、QtCreator和CLion，对基于CMake的构建系统提供了本地支持。这些IDE提供了用户界面，用于选择要使用的底层生成器，通常是在Makefile或基于Ninja的生成器之间进行选择。

请注意，在第一次调用CMake之后，不可能使用-G更改生成器。要更改生成器，必须删除生成目录，并且必须从头开始生成。在生成Visual Studio项目和解决方案文件时，最初运行cmake时可以使用其他几个选项。

可以使用cmake -T选项指定Visual Studio工具集：

bash 复制代码

# Build with the clang-cl toolset
cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T ClangCL
# Build targeting Windows XP
cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T v120_xp

-A选项指定_target_体系结构，-T选项可用于指定所用工具链的详细信息。例如，可以使用-Thost=x64来选择主机工具的64位版本。以下内容演示了如何使用64位工具，以及如何构建64位目标体系结构：

bash 复制代码

cmake .. -G "Visual Studio 16 2019" -A x64 -Thost=x64

3. 在cmake gui中选择生成器

Configure按钮触发一个新对话框，选择要使用的CMake生成器。

命令行上可用的所有生成器在cmake gui中也可用。

选择Visual Studio生成器时，可以使用其他选项来设置要为其生成的体系结构。

三. 设置生成变量

软件项目通常需要在调用CMake时在命令行上设置变量。下表列出了一些最常用的CMake变量：

变量	描述
`CMAKE_PREFIX_PATH`	要搜索的依赖程序包路径
`CMAKE_MODULE_PATH`	搜索其他CMake模块的路径
`CMAKE_BUILD_TYPE`	构建类型选项, 例如 `Debug` or `Release`, 确定调试/优化标志. 这只适用于单配置构建系统，例如 `Makefile` and `Ninja`. Visual Studio和Xcode等多配置构建系统会忽略此设置.
`CMAKE_INSTALL_PREFIX`	当使用 `install`选项时，使用此路径将软件安装到的位置
`CMAKE_TOOLCHAIN_FILE`	包含交叉编译数据的文件，例如 `toolchains and sysroots`.
`BUILD_SHARED_LIBS`	是否为不带类型的命令，例如`add_library()`构建共享库而不是静态库 commands used without a type
`CMAKE_EXPORT_COMPILE_COMMANDS`	生成一个`compile_commands.json`文件，用于基于clang的工具

1. 在命令行上设置变量

创建初始构建时，可以在命令行上设置CMake变量：

bash 复制代码

mkdir build
cd build
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug

或者稍后在随后调用cmake时：

bash 复制代码

cd build
cmake . -DCMAKE_BUILD_TYPE=Debug

-U标志可用于取消设置cmake命令行上的变量：

bash 复制代码

cd build
cmake . -UMyPackage_DIR

最初在命令行上创建的CMake构建系统可以使用CMake gui进行修改，反之亦然。

cmake工具允许使用-C选项指定用于填充初始缓存的文件。这对于简化重复需要相同缓存项的命令和脚本非常有用。

2. 使用cmake gui设置变量

可以使用Add Entry按钮在cmake gui中设置变量。这将触发一个新对话框来设置变量的值。

3. CMake缓存

当执行CMake时，它需要找到编译器、工具和依赖项的位置。它还需要能够一致地重新生成构建系统，以使用相同的编译/链接标志和依赖项路径。这样的参数也需要由用户配置，因为它们是特定于用户系统的路径和选项。

首次执行时，CMake会在构建目录中生成一个CMakeCache.txt文件，其中包含此类工件的键值对。用户可以通过运行cmake gui或ccmake工具来查看或编辑缓存文件。这些工具提供了一个交互式界面，用于在编辑缓存值后重新配置所提供的软件和重新生成构建系统。每个高速缓存条目可以具有相关联的短帮助文本，该文本显示在用户界面工具中。

四. 预设

CMake理解一个文件CMakePresets.json及其特定于用户的对应文件CMakeUserPresets.json，用于保存常用配置设置的预设。这些预设可以设置生成目录、生成器、缓存变量、环境变量和其他命令行选项。所有这些选项都可以由用户覆盖。cmake预设手册中列出了cmake预设.json格式的全部详细信息。

1. 在命令行上使用预设

当使用cmake命令行工具时，可以使用--preset选项调用预设。如果指定了--preset，则不需要生成器和生成目录，但可以指定它们来覆盖它们。例如，如果您有以下CMakePresets.json文件：

css 复制代码

{
  "version": 1,
  "configurePresets": [
    {
      "name": "ninja-release",
      "binaryDir": "${sourceDir}/build/${presetName}",
      "generator": "Ninja",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Release"
      }
    }
  ]
}

然后运行以下操作：

bash 复制代码

cmake -S /path/to/source --preset=ninja-release

这将在/path/to/source/build/ninja发行版中使用ninja生成器生成一个构建目录，并且CMAKE_build_TYPE设置为release。

如果您想查看可用预设的列表，可以运行：

bash 复制代码

cmake -S /path/to/source --list-presets

这将列出/path/to/source/CMakePresets.json和/path/to_source/CMakeUsersPresets.json中可用的预设，而不生成构建树。

2. 在cmake gui中使用预设

如果项目有可用的预设，无论是通过CMakePresets.json还是CMakeUserPresets.json，预设列表都将出现在源目录和二进制目录之间的cmakegui中的下拉菜单中。选择预设会设置二进制目录、生成器、环境变量和缓存变量，但在选择预设后，所有这些选项都可以被覆盖。

五. 调用Buildsystem

生成构建系统后，可以通过调用特定的构建工具来构建软件。在IDE生成器的情况下，这可能涉及将生成的项目文件加载到IDE中以调用构建。

CMake知道调用构建所需的特定构建工具，因此通常，要在生成后从命令行构建构建系统或项目，可以在构建目录中调用以下命令：

bash 复制代码

cmake --build .

--build标志为cmake工具启用特定的操作模式。它调用与生成器或用户配置的构建工具关联的CMAKE_MAKE_PROGRAM命令。
--build模式还接受参数--target来指定要构建的特定目标，例如特定库、可执行文件或自定义目标，或特定的特殊目标（如install）：

bash 复制代码

cmake --build . --target myexe

在多配置生成器的情况下，--build模式还接受--config参数，以指定要构建的特定配置：

bash 复制代码

cmake --build . --target myexe --config Release

如果生成器生成特定于配置的构建系统，则--config选项无效，该配置是在使用cmake_BUILD_TYPE变量调用cmake时选择的。

有些构建系统省略了在构建过程中调用的命令行的详细信息。--verbose标志可用于显示以下命令行：

bash 复制代码

cmake --build . --target myexe --verbose

--build模式还可以通过在--之后列出特定的命令行选项，将它们传递给底层构建工具。这对于为生成工具指定选项非常有用，例如在CMake不提供高级用户界面的作业失败后继续生成。

对于所有生成器，都可以在调用CMake之后运行底层构建工具。例如，make可以在用Unix Makefiles生成器生成后执行以调用构建，或者在用ninja生成器生成后使用ninja等执行。IDE构建系统通常提供用于构建也可以调用的项目的命令行工具。

1. 选择目标

CMake文件中描述的每个可执行文件和库都是一个构建目标，构建系统可以描述自定义目标，供内部使用，也可以供用户使用，例如创建文档。

CMake为所有提供CMake文件的构建系统提供了一些内置目标。


选项	说明
all	Makefile和Ninja生成器使用的默认目标。生成生成系统中的所有目标，但被其EXCLUDE_FROM_all目标属性或EXCLUDE-FROM_all目录属性排除的目标除外。名称ALL_BUILD用于Xcode和Visual Studio生成器的此目的。
help	列出可用于生成的目标。当使用Unix Makefiles或Ninja生成器时，此目标可用，并且确切的输出是特定于工具的。
clean	删除生成的对象文件和其他输出文件。基于Makefile的生成器为每个目录创建一个干净的目标，这样就可以清理单个目录。忍者工具提供了自己的细粒度-t清洁系统。
test	运行测试。只有当CMake文件提供基于CTest的测试时，此目标才自动可用。另请参阅运行测试。
install	安装软件。只有当软件使用install()命令定义安装规则时，此目标才自动可用。另请参阅软件安装。
package	创建一个二进制包。只有当CMake文件提供基于CPack的包时，此目标才自动可用。
package_source	创建源程序包。只有当CMake文件提供基于CPack的包时，此目标才自动可用。

2. 指定生成程序

生成器	默认的生成程序	可选项
XCode	`xcodebuild`
Unix Makefiles	`make`
NMake Makefiles	`nmake`	`jom`
NMake Makefiles JOM	`jom`	`nmake`
MinGW Makefiles	`mingw32-make`
MSYS Makefiles	`make`
Ninja	`ninja`
Visual Studio	`msbuild`
Watcom WMake	`wmake`

六. 软件安装

可以在CMAKE缓存中设置CMAKE_INSTALL_PREFIX变量，以指定安装所提供软件的位置。如果提供的软件具有使用install()命令指定的安装规则，则它们将把工件安装到该前缀中。在Windows上，默认安装位置对应于ProgramFiles系统目录，该目录可能是特定于体系结构的。在Unix主机上，/usr/local是默认的安装位置。CMAKE_INSTALL_PREFIX变量总是指目标文件系统上的安装前缀。在交叉编译或打包场景中，如果系统根是只读的，或者系统根应该保持原始状态，则可以将CMAKE_STAGING_PREFIX变量设置为实际安装文件的位置。

命令：

bash 复制代码

cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_SYSROOT=$HOME/root -DCMAKE_STAGING_PREFIX=/tmp/package
cmake --build .
cmake --build . --target install

导致文件被安装到主机上的路径，如/tmp/package/lib/libfoo.so。主机上的/usr/local位置不受影响。某些提供的软件可能会指定卸载规则，但CMake本身默认不会生成此类规则。

七. 运行测试

ctest工具随CMake发行版一起提供，用于执行所提供的测试并报告结果。测试构建目标用于运行所有可用的测试，但ctest工具允许对运行哪些测试、如何运行测试以及如何报告结果进行精细控制。在生成目录中执行ctest相当于运行测试目标：

bash 复制代码

ctest

可以传递正则表达式以仅运行与该表达式匹配的测试。要仅以Qt的名义运行测试，请执行以下操作：

bash 复制代码

ctest -R Qt

正则表达式也可以排除测试。要只运行名称中没有Qt的测试，请执行以下操作：

bash 复制代码

ctest -E Qt

通过将-j参数传递给ctest，可以并行运行测试：

bash 复制代码

ctest -R Qt -j8