Cmake用户交互指南

一. 介绍

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

1. 命令行cmake工具

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

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选项覆盖默认生成器：

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版本提供的其他方式

  cmake .. -G "Visual Studio 2019"
  cmake .. -G "Visual Studio 16"
  cmake .. -G "Visual Studio 16 2019"
  

  Visual Studio生成器可以针对不同的体系结构。可以使用-A选项指定目标系统结构：

  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工具集：

# 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位目标体系结构：

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变量：

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

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

cd build
cmake . -DCMAKE_BUILD_TYPE=Debug

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

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文件：

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

然后运行以下操作：

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

这将在/path/to/source/build/ninja发行版中使用ninja生成器生成一个构建目录，并且CMAKE_build_TYPE设置为release。
如果您想查看可用预设的列表，可以运行：

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

cmake --build .

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

cmake --build . --target myexe

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

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

如果生成器生成特定于配置的构建系统，则--config选项无效，该配置是在使用cmake_BUILD_TYPE变量调用cmake时选择的。
有些构建系统省略了在构建过程中调用的命令行的详细信息。--verbose标志可用于显示以下命令行：

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变量设置为实际安装文件的位置。
命令：

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相当于运行测试目标：

ctest

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

ctest -R Qt

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

ctest -E Qt

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

ctest -R Qt -j8