cmake(1)

概要

Generate a Project Buildsystem
 cmake [<options>] <path-to-source | path-to-existing-build>
 cmake [<options>] -S <path-to-source> -B <path-to-build>

Build a Project
 cmake --build <dir> [<options>] [-- <build-tool-options>]

Install a Project
 cmake --install <dir> [<options>]

Open a Project
 cmake --open <dir>

Run a Script
 cmake [-D <var>=<value>]... -P <cmake-script-file>

Run a Command-Line Tool
 cmake -E <command> [<options>]

Run the Find-Package Tool
 cmake --find-package [<options>]

Run a Workflow Preset
 cmake --workflow [<options>]

View Help
 cmake --help[-<topic>]

描述

cmake 可执行文件是跨平台构建系统生成器 CMake 的命令行界面。上面的“概要”列出了该工具可以执行的各种操作，如下文所述。

要使用 CMake 构建软件项目，Generate a Project Buildsystem。可选择使用 cmake 来 Build a Project、Install a Project 或直接运行相应的构建工具（例如 make）。 cmake 也可用于 View Help。

其他操作旨在供使用 CMake 语言 编写脚本的软件开发人员使用，以支持他们的构建。

对于可用于代替 cmake 的图形用户界面，请参阅:manual:ccmake <ccmake(1)> 和 cmake-gui。有关 CMake 测试和打包工具的命令行界面，请参阅 ctest 和 cpack。

有关 CMake 的更多信息，请参见本手册末尾的链接。

CMake 构建系统简介

buildsystem 描述了如何使用 build 工具 从项目的源代码构建项目的可执行文件和库以自动化该过程。例如，构建系统可能是一个“Makefile”，用于与命令行“make”工具一起使用，或者是一个用于集成开发环境（IDE）的项目文件。为了避免维护多个这样的构建系统，项目可以使用以 CMake 语言 编写的文件抽象地指定其构建系统。从这些文件中，CMake 通过称为 generator 的后端为每个用户在本地生成一个首选的构建系统。

要使用 CMake 生成构建系统，必须选择以下内容：

源代码树

包含项目提供的源文件的顶级目录。该项目使用 cmake-language(7) 手册中描述的文件指定其构建系统，从名为 CMakeLists.txt 的顶级文件开始。这些文件指定构建目标及其依赖项，如 cmake-buildsystem(7) 手册中所述。

建树

要存储构建系统文件和构建输出工件（例如可执行文件和库）的顶级目录。 CMake 将编写一个 CMakeCache.txt 文件来将该目录标识为构建树并存储持久性信息，例如构建系统配置选项。

要维护原始源代码树，请使用单独的专用构建树执行 out-of-source 构建。还支持将构建树放置在与源树相同的目录中的 in-source 构建，但不鼓励这样做。

生成器

这选择了要生成的构建系统的种类。有关所有生成器的文档，请参阅 cmake-generators(7) 手册。运行 cmake --help 查看本地可用的生成器列表。可以选择使用下面的 -G 选项来指定生成器，或者简单地接受 CMake 为当前平台选择的默认值。

当使用 命令行构建工具生成器 之一时，CMake 期望编译器工具链所需的环境已经在 shell 中配置。使用 IDE 构建工具生成器 之一时，不需要特定的环境。

生成项目构建系统

使用以下命令签名之一运行 CMake 以指定源和构建树并生成构建系统：

cmake [<options>] <path-to-source>

使用当前工作目录作为构建树，并将``<path-to-source>``用作源树。指定的路径可以是绝对路径，也可以是相对于当前工作目录的相对路径。源代码树必须包含一个 CMakeLists.txt 文件并且必须 不 包含一个 CMakeCache.txt 文件，因为后者标识一个现有的构建树。例如：

$ mkdir build ; cd build
$ cmake ../src

cmake [<options>] <path-to-existing-build>

使用 <path-to-existing-build> 作为构建树，并从其 CMakeCache.txt 文件加载源树的路径，该文件必须已经由之前运行的 CMake 生成.指定的路径可以是绝对路径，也可以是相对于当前工作目录的相对路径。例如：

$ cd build
$ cmake .

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

在 3.13 版本加入.

使用 <path-to-build> 作为构建树，使用 <path-to-source> 作为源树。指定的路径可以是相对于当前工作目录的绝对路径或相对路径。源代码树必须包含一个“CMakeLists.txt”文件。如果构建树不存在，将自动创建它。例如：

$ cmake -S src -B build

在所有情况下，<options> 可以是零个或多个下面的 Options。

上述用于指定源代码和构建树的样式可以混合使用。使用 -S 或 -B 指定的路径始终分别分类为源树或构建树。使用普通参数指定的路径根据其内容和前面给出的路径类型进行分类。如果只给出了一种类型的路径，则当前工作目录 (cwd) 用于另一种。例如：

命令行	源目录	构建目录
cmake 源代码	源代码	cwd
``cmake 构建``（现有）	加载	构建
cmake -S 源	源代码	cwd
cmake -S src build	源代码	构建
cmake -S src -B 构建	源代码	构建
cmake -B 构建	cwd	构建
cmake -B build src	源代码	构建
cmake -B build -S src	源代码	构建

在 3.23 版本发生变更: 当指定多个源路径时，CMake 会发出警告。这从未被正式记录或支持，但旧版本意外地接受了多个源路径并使用了最后指定的路径。避免传递多个源路径参数。

生成构建系统后，可以使用相应的本机构建工具来构建项目。例如，在使用 Unix Makefiles 生成器后，可以直接运行 make：

$ make
$ make install

或者，可以使用 cmake 通过自动选择和调用适当的本机构建工具来 Build a Project。

选项

-S <path-to-source>

要构建的 CMake 项目的根目录路径。

-B <path-to-build>

CMake 将用作构建目录根目录的目录路径。

如果该目录不存在，CMake 会创建它。

-C <initial-cache>

预加载脚本以填充缓存。

当 CMake 首次在一个空的构建树中运行时，它会创建一个“CMakeCache.txt”文件并使用项目的可自定义设置填充它。此选项可用于指定在第一次通过项目的 CMake 列表文件之前加载缓存条目的文件。加载的条目优先于项目的默认值。给定的文件应该是一个 CMake 脚本，其中包含使用 CACHE 选项的 set() 命令，而不是缓存格式文件。

脚本中对 CMAKE_SOURCE_DIR 和 CMAKE_BINARY_DIR 的引用评估为顶级源代码和构建树。

-D <var>:<type>=<value>, -D <var>=<value>

创建或更新 CMake CACHE 条目。

当 CMake 首次在一个空的构建树中运行时，它会创建一个“CMakeCache.txt”文件并使用项目的可自定义设置填充它。此选项可用于指定优先于项目默认值的设置。可以根据需要为尽可能多的“CACHE”条目重复该选项。

如果给出了 :<type> 部分，它必须是 set() 命令文档为其 CACHE 签名指定的类型之一。如果省略 :<type> 部分，如果条目不存在，则将创建没有类型的条目。如果项目中的命令将类型设置为“PATH”或“FILEPATH”，则“<value>”将转换为绝对路径。

此选项也可以作为单个参数给出：-D<var>:<type>=<value> 或``-D<var>=<value>``。

重要的是要注意“-C”和“-D”参数的顺序很重要。它们将按照列出的顺序执行，最后一个参数优先于前面的参数。例如，如果您指定“-DCMAKE_BUILD_TYPE=Debug”，后跟一个“-C”参数和一个调用的文件：

set(CMAKE_BUILD_TYPE "Release" CACHE STRING "" FORCE)

那么 -C 参数将优先，CMAKE_BUILD_TYPE 将设置为 Release。但是，如果 -D 参数出现在 -C 参数之后，它将被设置为 Debug。

如果 -C 文件中的 set(... CACHE ...) 调用不使用 FORCE，而 -D 参数设置相同的变量，则由于非``FORCE`` set(... CACHE ...) 调用的性质，无论顺序如何，-D 参数都将优先。

-U <globbing_expr>

从 CMake CACHE 中删除匹配条目。

此选项可用于从“CMakeCache.txt”文件中删除一个或多个变量，支持使用“*”和“?”的通配表达式。可以根据需要为尽可能多的“CACHE”条目重复该选项。

小心使用，你可以让你的 CMakeCache.txt 不工作。

-G <generator-name>

指定构建系统生成器。

CMake 可能在某些平台上支持多个本机构建系统。生成器负责生成特定的构建系统。可能的生成器名称在 cmake-generators(7) 手册中指定。

如果未指定，CMake 会检查 CMAKE_GENERATOR 环境变量，否则会回退到内置默认选择。

-T <toolset-spec>

生成器的工具集规范（如果支持）。

一些 CMake 生成器支持工具集规范来告诉本机构建系统如何选择编译器。有关详细信息，请参阅 CMAKE_GENERATOR_TOOLSET 变量。

-A <platform-name>

如果生成器支持，请指定平台名称。

一些 CMake 生成器支持将平台名称提供给本机构建系统以选择编译器或 SDK。有关详细信息，请参阅 CMAKE_GENERATOR_PLATFORM 变量。

--toolchain <path-to-file>

指定交叉编译工具链文件，相当于设置 CMAKE_TOOLCHAIN_FILE 变量。

--install-prefix <directory>

指定安装目录，由 CMAKE_INSTALL_PREFIX 变量使用。必须是绝对路径。

-Wno-dev

禁止开发人员警告。

抑制针对 CMakeLists.txt 文件作者的警告。默认情况下，这也会关闭弃用警告。

-Wdev

启用开发人员警告。

启用针对 CMakeLists.txt 文件作者的警告。默认情况下，这也会打开弃用警告。

-Wdeprecated

启用弃用的功能警告。

为使用已弃用的功能启用警告，这是针对 CMakeLists.txt 文件的作者。

-Wno-deprecated

禁止弃用的功能警告。

禁止使用已弃用功能的警告，这些警告是针对“CMakeLists.txt”文件的作者的。

-Werror=<what>

将 CMake 警告视为错误。 <what> 必须是以下之一：

开发

使开发人员警告错误。

为 CMakeLists.txt 文件错误的作者发出警告。默认情况下，这也会将不推荐使用的警告作为错误打开。

已弃用

使不推荐使用的宏和函数警告错误。

对不推荐使用的宏和函数的使用发出警告，这是针对 CMakeLists.txt 文件的作者，错误。

-Wno-error=<what>

不要将 CMake 警告视为错误。 <what> 必须是以下之一：

开发

发出针对 CMakeLists.txt 文件而非错误的作者的警告。默认情况下，这也会将不推荐使用的警告作为错误关闭。

已弃用

对不推荐使用的宏和函数的使用发出警告，这是针对 CMakeLists.txt 文件的作者，而不是错误。

--fresh

在 3.24 版本加入.

执行构建树的全新配置。这将删除任何现有的 CMakeCache.txt 文件和关联的 CMakeFiles/ 目录，并从头开始重新创建它们。

-L[A][H]

列出非高级缓存变量。

列出 CACHE 变量将运行 CMake 并列出 CMake CACHE 中未标记为 INTERNAL 或 ADVANCED 的所有变量。这将有效地显示当前的 CMake 设置，然后可以使用 -D 选项进行更改。更改某些变量可能会导致创建更多变量。如果指定了``A``，那么它也会显示高级变量。如果指定了``H``，它还会显示每个变量的帮助。

-N

仅查看模式。

只加载缓存。不要实际运行配置和生成步骤。

--graphviz=<file>

生成依赖关系的 graphviz，有关更多信息，请参见:module:CMakeGraphVizOptions。

生成一个 graphviz 输入文件，它将包含项目中的所有库和可执行依赖项。有关详细信息，请参阅 CMakeGraphVizOptions 的文档。

--system-information [file]

转储有关此系统的信息。

转储有关当前系统的各种信息。如果从 CMake 项目的二叉树的顶部运行，它将转储其他信息，例如缓存、日志文件等。

--log-level=<level>

设置日志``<level>``。

message() 命令只会输出指定日志级别或更高级别的消息。有效的日志级别是“ERROR”、“WARNING”、“NOTICE”、“STATUS”（默认）、“VERBOSE”、“DEBUG”或“TRACE” .

要在 CMake 运行之间保持日志级别，请将 CMAKE_MESSAGE_LOG_LEVEL 设置为缓存变量。如果同时给出了命令行选项和变量，则命令行选项优先。

出于向后兼容性的原因，--loglevel 也被接受为该选项的同义词。

在 3.25 版本加入: 有关查询当前消息日志级别 <query_message_log_level> 的方法，请参阅 cmake_language() 命令。

--log-context

启用 message() 命令输出附加到每条消息的上下文。

此选项打开仅显示当前 CMake 运行的上下文。要显示所有后续 CMake 运行的上下文，请将 CMAKE_MESSAGE_CONTEXT_SHOW 设置为缓存变量。当给出此命令行选项时， CMAKE_MESSAGE_CONTEXT_SHOW 将被忽略。

--debug-trycompile

不要删除为 try_compile() / try_run() 调用创建的文件和目录。这在调试失败的检查时很有用。

请注意:command:try_compile 的一些使用可能使用相同的构建树，如果一个项目执行多个 try_compile()，这将限制此选项的有用性。例如，这样的使用可能会改变结果，因为来自先前尝试编译的工件可能会导致不同的测试错误地通过或失败。此选项最好仅在调试时使用。

（关于前面的内容， try_run() 命令实际上是一个 try_compile()。两者的任何组合都受所描述的潜在问题的影响。）

在 3.25 版本加入: 启用此选项后，每次尝试编译检查都会打印一条日志消息，报告执行检查的目录。

--debug-output

将 cmake 置于调试模式。

在 cmake 运行期间打印额外信息，例如使用 message(SEND_ERROR) 调用的堆栈跟踪。

--debug-find

将 cmake find 命令置于调试模式。

在 cmake 运行到标准错误期间打印额外的查找调用信息。输出是为人类消费而设计的，而不是为解析而设计的。另请参阅 CMAKE_FIND_DEBUG_MODE 变量以调试项目的更多本地部分。

--debug-find-pkg=<pkg>[,...]

在调用 find_package(<pkg>) 时将 cmake find 命令置于调试模式，其中 <pkg> 是给定的以逗号分隔的案例列表中的条目-敏感的包名称。

类似于 --debug-find，但将范围限制在指定的包中。

--debug-find-var=<var>[,...]

当使用“<var>”作为结果变量调用时，将 cmake find 命令置于调试模式，其中“<var>”是给定逗号分隔列表中的条目。

类似于 --debug-find，但将范围限制为指定的变量名称。

--trace

将 cmake 置于跟踪模式。

打印所有呼叫的踪迹以及来自哪里。

--trace-expand

将 cmake 置于跟踪模式。

类似于 --trace，但变量已扩展。

--trace-format=<format>

将 cmake 置于跟踪模式并设置跟踪输出格式。

<format> 可以是以下值之一。

人类

以人类可读的格式打印每条跟踪线。这是默认格式。

json-v1

将每一行打印为单独的 JSON 文档。每个文档都由换行符 (\n) 分隔。保证 JSON 文档中不会出现换行符。

JSON 跟踪格式

{
  "file": "/full/path/to/the/CMake/file.txt",
  "line": 0,
  "cmd": "add_executable",
  "args": ["foo", "bar"],
  "time": 1579512535.9687231,
  "frame": 2,
  "global_frame": 4
}

成员是：

文件

调用函数的 CMake 源文件的完整路径。

线

file 中函数调用开始的行。

line_end

如果函数调用跨越多行，则此字段将设置为函数调用结束的行。如果函数调用跨越一行，则该字段将被取消设置。该字段是在 json-v1 格式的次要版本 2 中添加的。

推迟

当函数调用被 cmake_language(DEFER) 延迟时出现的可选成员。如果存在，它的值是一个包含延迟调用的字符串 <id>。

命令

被调用的函数的名称。

参数

所有函数参数的字符串列表。

时间

函数调用的时间戳（自纪元以来的秒数）。

框架

在当前正在处理的“CMakeLists.txt”上下文中，被调用函数的堆栈帧深度。

global_frame

被调用函数的堆栈帧深度，在跟踪中涉及的所有“CMakeLists.txt”文件中进行全局跟踪。该字段是在 json-v1 格式的次要版本 2 中添加的。

此外，输出的第一个 JSON 文档包含当前主要和次要版本的 version 键

JSON版本格式

{
  "version": {
    "major": 1,
    "minor": 2
  }
}

成员是：

版本

指示 JSON 格式的版本。该版本具有遵循语义版本约定的主要和次要组件。

--trace-source=<file>

将 cmake 置于跟踪模式，但仅输出指定文件的行。

允许多个选项。

--trace-redirect=<file>

将 cmake 置于跟踪模式并将跟踪输出重定向到文件而不是 stderr。

--warn-uninitialized

警告未初始化的值。

使用未初始化的变量时打印警告。

--warn-unused-vars

什么也没做。在 CMake 3.2 及以下版本中，这启用了有关未使用变量的警告。在 CMake 版本 3.3 到 3.18 中，该选项已损坏。在 CMake 3.19 及更高版本中，该选项已被删除。

--no-warn-unused-cli

不要警告命令行选项。

找不到在命令行上声明但未使用的变量。

--check-system-vars

查找系统文件中变量使用的问题。

通常，仅在 CMAKE_SOURCE_DIR 和 CMAKE_BINARY_DIR 中搜索未使用和未初始化的变量。这个标志告诉 CMake 对其他文件也发出警告。

--compile-no-warning-as-error

忽略目标属性 COMPILE_WARNING_AS_ERROR 和变量 CMAKE_COMPILE_WARNING_AS_ERROR ，防止警告被视为编译错误。

--profiling-output=<path>

与 --profiling-format 结合使用以输出到给定路径。

--profiling-format=<file>

启用以给定格式输出 CMake 脚本的分析数据。

这有助于对执行的 CMake 脚本进行性能分析。应使用第三方应用程序将输出处理为人类可读的格式。

目前支持的值是： google-trace Google Trace 格式的输出，可以通过 Google Chrome 的 about:tracing 选项卡或使用 Trace Compass 等工具的插件进行解析。

--preset <preset>, --preset=<preset>

从``<path-to-source>/CMakePresets.json`` 和``<path-to-source>/CMakeUserPresets.json`` 中读取:manual:preset <cmake-presets(7)>。预设可以指定生成器和构建目录，以及要传递给 CMake 的变量列表和其他参数。当前工作目录必须包含 CMake 预设文件。 CMake GUI 也可以识别 CMakePresets.json 和 CMakeUserPresets.json 文件。有关这些文件的完整详细信息，请参阅 cmake-presets(7)。

在所有其他命令行选项之前读取预设。预设指定的选项（变量、生成器等）都可以通过在命令行上手动指定来覆盖。例如，如果预设将名为“MYVAR”的变量设置为“1”，但用户使用“-D”参数将其设置为“2”，则值“2”是首选。

--list-presets[=<type>]

列出指定的 <type> 的可用预设。 <type> 的有效值为``configure``、build、test、package 或``all``。如果省略``<type>``，则假定为``configure``。当前工作目录必须包含 CMake 预设文件。

建立一个项目

CMake 提供了一个命令行签名来构建一个已经生成的项目二叉树：

cmake --build <dir>             [<options>] [-- <build-tool-options>]
cmake --build --preset <preset> [<options>] [-- <build-tool-options>]

这使用以下选项抽象了本机构建工具的命令行界面：

--build <dir>

要构建的项目二进制目录。这是必需的（除非指定了预设）并且必须是第一个。

--preset <preset>, --preset=<preset>

使用构建预设来指定构建选项。项目二进制目录是从 configurePreset 键推断出来的。当前工作目录必须包含 CMake 预设文件。有关详细信息，请参阅 preset。

--list-presets

列出可用的构建预设。当前工作目录必须包含 CMake 预设文件。

-j [<jobs>], --parallel [<jobs>]

在 3.12 版本加入.

构建时要使用的最大并发进程数。如果省略``<jobs>``，则使用本机构建工具的默认编号。

CMAKE_BUILD_PARALLEL_LEVEL 环境变量（如果设置）指定未给出此选项时的默认并行级别。

一些本机构建工具总是并行构建。使用 <jobs> 的值 1 可用于限制为单个作业。

-t <tgt>..., --target <tgt>...

构建 <tgt> 而不是默认目标。可以给出多个目标，以空格分隔。

--config <cfg>

对于多配置工具，选择配置``<cfg>``。

--clean-first

首先构建目标 clean，然后构建。 （只清理，使用 --target clean。）

--resolve-package-references=<value>

在 3.23 版本加入.

在构建之前解析来自外部包管理器（例如 NuGet）的远程包引用。当``<value>`` 设置为``on``（默认）时，将在构建目标之前恢复包。当``<value>`` 设置为``only`` 时，将恢复包，但不会执行构建。当``<value>`` 设置为``off`` 时，不会恢复任何包。

如果目标未定义任何包引用，则此选项不执行任何操作。

可以在构建预设中指定此设置（使用“resolvePackageReferences”）。如果指定了此命令行选项，则预设设置将被忽略。

如果未提供命令行参数或预设选项，将评估特定于环境的缓存变量以决定是否应执行包恢复。

使用 Visual Studio 生成器时，包引用是使用 VS_PACKAGE_REFERENCES 属性定义的。使用 NuGet 恢复包引用。可以通过将“CMAKE_VS_NUGET_PACKAGE_RESTORE”变量设置为“OFF”来禁用它。

--use-stderr

忽略。行为在 CMake >= 3.0 中是默认的。

-v, --verbose

启用详细输出 - 如果支持 - 包括要执行的构建命令。

如果设置了 VERBOSE 环境变量或 CMAKE_VERBOSE_MAKEFILE 缓存变量，则可以省略此选项。

--

将剩余选项传递给本机工具。

不带任何选项运行 cmake --build 以获得快速帮助。

安装项目

CMake 提供了一个命令行签名来安装一个已经生成的项目二叉树：

cmake --install <dir> [<options>]

这可以在构建项目后使用，以在不使用生成的构建系统或本机构建工具的情况下运行安装。选项是：

--install <dir>

要安装的项目二进制目录。这是必需的，必须是第一个。

--config <cfg>

对于多配置生成器，选择配置``<cfg>``。

--component <comp>

基于组件的安装。只安装组件``<comp>``。

--default-directory-permissions <permissions>

默认目录安装权限。格式为“<u=rwx,g=rx,o=rx>”的权限。

--prefix <prefix>

覆盖安装前缀 CMAKE_INSTALL_PREFIX。

--strip

安装前剥离。

-v, --verbose

启用详细输出。

如果设置了 VERBOSE 环境变量，则可以省略此选项。

不带任何选项运行 cmake --install 以获得快速帮助。

打开一个项目

cmake --open <dir>

在关联的应用程序中打开生成的项目。这仅由某些生成器支持。

运行脚本

cmake [-D <var>=<value>]... -P <cmake-script-file> [-- <unparsed-options>...]

-D <var>=<value>

为脚本模式定义一个变量。

-P <cmake-script-file>

将给定的 cmake 文件处理为用 CMake 语言编写的脚本。没有执行配置或生成步骤，也没有修改缓存。如果使用“-D”定义变量，则必须在“-P”参数之前完成。

-- 之后的任何选项都不会被 CMake 解析，但它们仍然包含在传递给脚本的 CMAKE_ARGV<n> 变量集中（包括 ``--``本身）。

运行命令行工具

CMake 通过签名提供内置的命令行工具

cmake -E <command> [<options>]

-E [help]

运行“cmake -E”或“cmake -E help”以获得命令摘要。

可用的命令是：

capabilities

在 3.7 版本加入.

以 JSON 格式报告 cmake 功能。输出是一个具有以下键的 JSON 对象：

版本

带有版本信息的 JSON 对象。关键是：

字符串

cmake --version 显示的完整版本字符串。

主要

整数形式的主版本号。

未成年人

整数形式的次要版本号。

补丁

整数形式的补丁级别。

后缀

cmake 版本后缀字符串。

是脏的

如果 cmake 构建来自脏树，则设置一个布尔值。

生成器

可用生成器列表。每个生成器都是一个具有以下键的 JSON 对象：

名字

包含生成器名称的字符串。

工具集支持

如果生成器支持工具集，则为“true”，否则为“false”。

平台支持

如果生成器支持平台，则为“true”，否则为“false”。

支持的平台

在 3.21 版本加入.

当生成器通过 CMAKE_GENERATOR_PLATFORM (-A ...) 支持平台规范时可能存在的可选成员。该值是已知受支持的平台列表。

额外的生成器

包含与生成器兼容的所有额外生成器的字符串列表。

fileApi

当 cmake-file-api(7) 可用时出现的可选成员。该值是一个具有一个成员的 JSON 对象：

请求

包含零个或多个支持的文件 API 请求的 JSON 数组。每个请求都是一个包含成员的 JSON 对象：

善良

指定一种受支持的 对象种类。

版本

一个 JSON 数组，每个元素都是一个 JSON 对象，包含指定非负整数版本组件的“主要”和“次要”成员。

服务器模式

如果 cmake 支持服务器模式，则为“true”，否则为“false”。自 CMake 3.20 以来始终为 false。

tls

在 3.25 版本加入.

如果启用了 TLS 支持，则为“true”，否则为“false”。

cat [--] <files>...

在 3.18 版本加入.

连接文件并在标准输出上打印。

--

在 3.24 版本加入.

添加了对双破折号参数“--”的支持。 cat 的基本实现不支持任何选项，因此使用以 - 开头的选项将导致错误。使用 -- 表示选项的结尾，以防文件以 - 开头。

chdir <dir> <cmd> [<arg>...]

更改当前工作目录并运行命令。

compare_files [--ignore-eol] <file1> <file2>

检查 <file1> 是否与 <file2> 相同。如果文件相同，则返回“0”，否则返回“1”。如果参数无效，则返回 2。

--ignore-eol

在 3.14 版本加入.

该选项意味着逐行比较并忽略 LF/CRLF 差异。

copy <file>... <destination>, copy -t <destination> <file>...

将文件复制到 <destination>``（文件或目录）。如果指定了多个文件，或者指定了“-t”，则“<destination>”必须是目录并且必须存在。如果未指定“-t”，则假定最后一个参数是“<目的地>”。不支持通配符。 ``copy 确实遵循符号链接。这意味着它不会复制符号链接，而是复制它指向的文件或目录。

在 3.5 版本加入: 支持多个输入文件。

在 3.26 版本加入: 支持“-t”参数。

copy_directory <dir>... <destination>

将 <dir>... 目录的内容复制到 <destination> 目录。如果 <destination> 目录不存在，它将被创建。 copy_directory 确实遵循符号链接。

在 3.5 版本加入: 支持多个输入目录。

在 3.15 版本加入: 当源目录不存在时，该命令现在失败。以前它通过创建一个空的目标目录成功。

copy_directory_if_different <dir>... <destination>

在 3.26 版本加入.

将 <dir>... 目录的更改内容复制到 <destination> 目录。如果 <destination> 目录不存在，它将被创建。

copy_directory_if_different 确实遵循符号链接。当源目录不存在时，命令失败。

copy_if_different <file>... <destination>

如果文件已更改，则将文件复制到 <destination>``（文件或目录）。如果指定了多个文件，``<destination> 必须是目录并且它必须存在。 copy_if_different 确实遵循符号链接。

在 3.5 版本加入: 支持多个输入文件。

create_symlink <old> <new>

创建一个符号链接 <new> 命名为 <old>。

在 3.13 版本加入: 支持在 Windows 上创建符号链接。

备注

<new> 符号链接将被创建的路径必须事先存在。

create_hardlink <old> <new>

在 3.19 版本加入.

创建一个硬链接 <new> 命名为 <old>。

备注

必须预先存在创建“<new>”硬链接的路径。 <old> 必须事先存在。

echo [<string>...]

将参数显示为文本。

echo_append [<string>...]

将参数显示为文本但不换行。

env [<options>] [--] <command> [<arg>...]

在 3.1 版本加入.

在修改后的环境中运行命令。选项是：

NAME=VALUE

将 NAME 的当前值替换为 VALUE。

--unset=NAME

取消设置 NAME 的当前值。

--modify ENVIRONMENT_MODIFICATION

在 3.25 版本加入.

将单个 ENVIRONMENT_MODIFICATION 操作应用于修改后的环境。

NAME=VALUE 和 --unset=NAME 选项分别等同于 --modify NAME=set:VALUE 和 --modify NAME=unset:。请注意，--modify NAME=reset: 将 NAME 重置为 cmake 启动时的值（或取消设置），而不是最近的 ``NAME=VALUE``选项。

--

在 3.24 版本加入.

添加了对双破折号参数“--”的支持。使用``--停止解释选项/环境变量并将下一个参数视为命令，即使它以-开头或包含``=。

environment

显示当前环境变量。

false

在 3.16 版本加入.

什么也不做，退出代码为 1。

make_directory <dir>...

创建``<dir>`` 目录。如有必要，也创建父目录。如果一个目录已经存在，它将被忽略。

在 3.5 版本加入: 支持多个输入目录。

md5sum <file>...

以“md5sum”兼容格式创建文件的 MD5 校验和：

351abe79cd3800b38cdfb25d45015a15  file1.txt
052f86c15bbde68af55c7f7b340ab639  file2.txt

sha1sum <file>...

在 3.10 版本加入.

以 sha1sum 兼容格式创建文件的 SHA1 校验和：

4bb7932a29e6f73c97bb9272f2bdc393122f86e0  file1.txt
1df4c8f318665f9a5f2ed38f55adadb7ef9f559c  file2.txt

sha224sum <file>...

在 3.10 版本加入.

以 sha224sum 兼容格式创建文件的 SHA224 校验和：

b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930  file1.txt
6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24  file2.txt

sha256sum <file>...

在 3.10 版本加入.

以 sha256sum 兼容格式创建文件的 SHA256 校验和：

76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc  file1.txt
15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea  file2.txt

sha384sum <file>...

在 3.10 版本加入.

以 sha384sum 兼容格式创建文件的 SHA384 校验和：

acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434  file1.txt
668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d  file2.txt

sha512sum <file>...

在 3.10 版本加入.

以 sha512sum 兼容格式创建文件的 SHA512 校验和：

2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89  file1.txt
7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d  file2.txt

remove [-f] <file>...

自 3.17 版本弃用.

删除文件。计划的行为是，如果任何列出的文件已经不存在，该命令将返回一个非零退出代码，但不会记录任何消息。 -f 选项改变了在这种情况下返回零退出代码（即成功）的行为。 remove 不遵循符号链接。这意味着它只删除符号链接而不删除它指向的文件。

实现有问题，总是返回 0。如果不破坏向后兼容性，就无法修复它。请改用 rm。

remove_directory <dir>...

自 3.17 版本弃用.

删除 <dir> 目录及其内容。如果目录不存在，它将被忽略。请改用 rm。

在 3.15 版本加入: 支持多个目录。

在 3.16 版本加入: 如果 <dir> 是目录的符号链接，则仅符号链接将被删除。

rename <oldname> <newname>

重命名文件或目录（在一个卷上）。如果具有 <newname> 名称的文件已经存在，那么它将被静默替换。

rm [-rRf] [--] <file|dir>...

在 3.17 版本加入.

删除文件``<file>`` 或目录``<dir>``。使用 -r 或 -R 递归删除目录及其内容。如果列出的任何文件/目录不存在，该命令将返回一个非零退出代码，但不会记录任何消息。 -f 选项改变了在这种情况下返回零退出代码（即成功）的行为。使用 -- 停止解释选项并将所有剩余参数视为路径，即使它们以 - 开头。

sleep <number>...

在 3.0 版本加入.

睡眠给定的秒数。

tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]

创建或提取 tar 或 zip 存档。选项是：

c

创建一个包含指定文件的新存档。如果使用，<pathname>... 参数是必需的。

x

从存档中提取到磁盘。

在 3.15 版本加入: <pathname>... 参数可用于仅提取选定的文件或目录。提取选定的文件或目录时，您必须提供它们的确切名称，包括路径，如 list (-t) 所示。

t

列出存档内容。

在 3.15 版本加入: <pathname>... 参数可用于仅列出选定的文件或目录。

v

产生详细的输出。

z

使用 gzip 压缩生成的存档。

j

使用 bzip2 压缩生成的存档。

J

在 3.1 版本加入.

使用 XZ 压缩生成的存档。

--zstd

在 3.15 版本加入.

使用 Zstandard 压缩生成的存档。

--files-from=<file>

在 3.1 版本加入.

从给定文件中读取文件名，每行一个。空行被忽略。行不能以 - 开头，除了 --add-file=<name> 以添加名称以 - 开头的文件。

--format=<format>

在 3.3 版本加入.

指定要创建的存档的格式。支持的格式有：7zip、gnutar、pax、paxr``（限制 pax，默认）和 ``zip。

--mtime=<date>

在 3.1 版本加入.

指定 tarball 条目中记录的修改时间。

--touch

在 3.24 版本加入.

使用当前本地时间戳而不是从存档中提取文件时间戳。

--

在 3.1 版本加入.

停止解释选项并将所有剩余参数视为文件名，即使它们以“-”开头。

在 3.1 版本加入: LZMA (7zip) 支持。

在 3.15 版本加入: 即使某些文件不可读，该命令现在仍会继续将文件添加到存档中。此行为与经典的“tar”工具更一致。该命令现在还会解析所有标志，如果提供了无效标志，则会发出警告。

time <command> [<args>...]

运行命令并显示运行时间。

在 3.5 版本加入: 该命令现在可以正确地将带有空格或特殊字符的参数传递给子进程。这可能会破坏使用自己的额外引号或转义来解决该错误的脚本。

touch <file>...

如果文件不存在，则创建 <file>。如果 <file> 存在，它正在改变 <file> 访问和修改时间。

touch_nocreate <file>...

如果文件存在但不创建它，请触摸该文件。如果文件不存在，它将被静默忽略。

true

在 3.16 版本加入.

什么都不做，退出代码为 0。

Windows 特定的命令行工具

以下 cmake -E 命令仅在 Windows 上可用：

delete_regv <key>

删除 Windows 注册表值。

env_vs8_wince <sdkname>

在 3.2 版本加入.

显示一个批处理文件，它为安装在 VS2005 中的提供的 Windows CE SDK 设置环境。

env_vs9_wince <sdkname>

在 3.2 版本加入.

显示一个批处理文件，它为安装在 VS2008 中的提供的 Windows CE SDK 设置环境。

write_regv <key> <value>

写入 Windows 注册表值。

运行查找包工具

CMake 为基于 Makefile 的项目提供了类似 pkg-config 的帮助程序：

cmake --find-package [<options>]

它使用 find_package() 搜索包并将结果标志打印到标准输出。这可以用来代替 pkg-config 在普通的基于 Makefile 的项目或基于 autoconf 的项目中查找已安装的库（通过 share/aclocal/cmake.m4）。

备注

由于某些技术限制，此模式未得到很好的支持。保留它是为了兼容性，但不应在新项目中使用。

运行工作流程预设

CMake Presets 提供了一种按顺序执行多个构建步骤的方法：

cmake --workflow [<options>]

选项是：

--workflow

使用以下选项之一选择 工作流程预设。

--preset <preset>, --preset=<preset>

使用工作流预设来指定工作流。项目二进制目录是从初始配置预设中推断出来的。当前工作目录必须包含 CMake 预设文件。有关详细信息，请参阅 preset。

--list-presets

列出可用的工作流程预设。当前工作目录必须包含 CMake 预设文件。

--fresh

执行构建树的全新配置。这将删除任何现有的 CMakeCache.txt 文件和关联的 CMakeFiles/ 目录，并从头开始重新创建它们。

查看帮助

要打印 CMake 文档中的选定页面，请使用

cmake --help[-<topic>]

使用以下选项之一：

-version [<file>], --version [<file>], /V [<file>]

显示程序名称/版本横幅并退出。 |文件|

-h, -H, --help, -help, -usage, /?

打印使用信息并退出。

用法描述了基本的命令行界面及其选项。

--help-full [<file>]

打印所有帮助手册并退出。

所有手册均以人类可读的文本格式印刷。 |文件|

--help-manual <man> [<file>]

打印一份帮助手册并退出。

指定的手册以人类可读的文本格式打印。 |文件|

--help-manual-list [<file>]

列出可用的帮助手册并退出。

该列表包含所有可以通过使用“--help-manual”选项后跟手册名称来获取帮助的手册。 |文件|

--help-command <cmd> [<file>]

打印一个命令的帮助并退出。

<cmd> 的 cmake-commands(7) 手册条目以人类可读的文本格式打印。 |文件|

--help-command-list [<file>]

列出具有可用帮助的命令并退出。

该列表包含所有可以通过使用“--help-command”选项后跟命令名称来获取帮助的命令。 |文件|

--help-commands [<file>]

打印 cmake-commands 手册并退出。

cmake-commands(7) 手册以人类可读的文本格式打印。 |文件|

--help-module <mod> [<file>]

打印一个模块的帮助并退出。

<mod> 的 cmake-modules(7) 手册条目以人类可读的文本格式打印。 |文件|

--help-module-list [<file>]

列出具有可用帮助的模块并退出。

该列表包含所有可以通过使用“--help-module”选项后跟模块名称来获取帮助的模块。 |文件|

--help-modules [<file>]

打印 cmake-modules 手册并退出。

cmake-modules(7) 手册以人类可读的文本格式打印。 |文件|

--help-policy <cmp> [<file>]

打印一项政策的帮助并退出。

<cmp> 的 cmake-policies(7) 手册条目以人类可读的文本格式打印。 |文件|

--help-policy-list [<file>]

列出具有可用帮助的策略并退出。

该列表包含所有可以通过使用“--help-policy”选项后跟策略名称来获取帮助的策略。 |文件|

--help-policies [<file>]

打印 cmake-policies 手册并退出。

cmake-policies(7) 手册以人类可读的文本格式打印。 |文件|

--help-property <prop> [<file>]

打印一个属性的帮助并退出。

<prop> 的 cmake-properties(7) 手册条目以人类可读的文本格式打印。 |文件|

--help-property-list [<file>]

列出具有可用帮助的属性并退出。

该列表包含所有可以通过使用“--help-property”选项后跟属性名称来获取帮助的属性。 |文件|

--help-properties [<file>]

打印 cmake-properties 手册并退出。

cmake-properties(7) 手册以人类可读的文本格式打印。 |文件|

--help-variable <var> [<file>]

打印一个变量的帮助并退出。

<var> 的 cmake-variables(7) 手册条目以人类可读的文本格式打印。 |文件|

--help-variable-list [<file>]

列出可用帮助的变量并退出。

该列表包含所有变量，可以通过使用“--help-variable”选项后跟变量名来获得帮助。 |文件|

--help-variables [<file>]

打印 cmake-variables 手册并退出。

cmake-variables(7) 手册以人类可读的文本格式打印。 |文件|

要查看项目可用的预设，请使用

cmake <source-dir> --list-presets

返回值（退出代码）

在正常终止时， cmake 可执行文件返回退出代码 0。

如果终止是由命令 message(FATAL_ERROR) 或其他错误条件引起的，则返回非零退出代码。

也可以看看

以下资源可用于获取使用 CMake 的帮助：

主页

https://cmake.org

学习 CMake 的主要起点。

在线文档和社区资源

https://cmake.org/文档

可在此网页上找到指向可用文档和社区资源的链接。

话语论坛

https://discourse.cmake.org

Discourse Forum 主持关于 CMake 的讨论和问题。