cmake(1)¶

概要¶

Generate a Project Buildsystem
 cmake [<options>] -B <path-to-build> [-S <path-to-source>]
 cmake [<options>] <path-to-source | path-to-existing-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 的命令行接口。上述摘要 (Synopsis) 列出了该工具可以执行的各种操作，具体描述见下文。

要使用 CMake 构建软件项目，请生成项目构建系统。您可以选择使用 cmake 来构建项目、安装项目，或者直接运行相应的构建工具（例如 make）。cmake 也可用于查看帮助。

其他操作旨在供软件开发者在编写 CMake 语言 脚本以支持其构建时使用。

对于可能替代 cmake 的图形用户界面，请参阅 ccmake 和 cmake-gui。对于 CMake 测试和打包功能的命令行接口，请参阅 ctest 和 cpack。

有关 CMake 的更多详细信息，请参阅本手册末尾的另请参阅链接。

CMake 构建系统介绍¶

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

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

源码树 (Source Tree)

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

构建树 (Build Tree)

用于存储构建系统文件和构建输出产物（例如可执行文件和库）的顶层目录。CMake 将写入一个 CMakeCache.txt 文件，以标识该目录为构建树，并存储持久化信息，例如构建系统配置选项。

为了保持源码树的原始状态，可以通过使用独立的专用构建树来执行 源码外构建 (out-of-source build)。同时也支持将构建树放在与源码树相同目录中的 源码内构建 (in-source build)，但不推荐这样做。

生成器

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

使用命令行构建工具生成器时，CMake 要求编译器工具链所需的环境已在 shell 中配置完毕。使用 IDE 构建工具生成器时，无需特定的环境。

生成项目构建系统¶

运行带有以下命令签名之一的 CMake，以指定源码树和构建树并生成构建系统

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

3.13 版本新增。

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

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 .

在所有情况下，<options> 都可以是下方的选项中的零个或多个。

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

命令行	源码目录	构建目录
`cmake -B build`	cwd	`构建`
`cmake -B build src`	`src`	`构建`
`cmake -B build -S src`	`src`	`构建`
`cmake src`	`src`	cwd
`cmake build` (现有的)	已加载	`构建`
`cmake -S src`	`src`	cwd
`cmake -S src build`	`src`	`构建`
`cmake -S src -B build`	`src`	`构建`

版本 3.23 变更: 当指定多个源码路径时，CMake 会发出警告。此行为从未被官方记录或支持，但旧版本会意外接受多个源码路径并使用最后指定的路径。请避免传递多个源码路径参数。

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

$ make
$ make install

或者，可以使用 cmake 来构建项目，它会自动选择并调用适当的原生构建工具。

选项¶

-S <path-to-source>¶: 要构建的 CMake 项目的根目录路径。

-B <path-to-build>¶

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

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

-C <initial-cache>¶

预加载一个脚本以填充缓存。

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

脚本中对 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，后面跟着一个调用

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

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

如果 -C 文件中的 set(... CACHE ...) 调用未使用 FORCE，且 -D 参数设置了相同的变量，由于非 FORCE 的 set(... CACHE ...) 调用的特性，无论顺序如何，-D 参数都会优先。

-U <globbing_expr>¶

从 CMake CACHE 中删除匹配的条目。

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

请谨慎使用，因为这可能会导致您的 CMakeCache.txt 无法正常工作。

-G <generator-name>¶

指定构建系统生成器。

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

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

-T <toolset-spec>¶

如果生成器支持，则指定工具集 (toolset)。

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

-A <platform-name>¶

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

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

--toolchain <path-to-file>¶: 3.21 版本新增。

指定交叉编译工具链文件，等同于设置 CMAKE_TOOLCHAIN_FILE 变量。相对路径被解释为相对于构建目录，如果找不到，则相对于源码目录。

--install-prefix <directory>¶: 3.21 版本新增。

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

--project-file <project-file-name>¶

4.0 版本新增。

指定替代的项目文件名。

这决定了 CMake 在配置项目时处理的顶层文件，以及 add_subdirectory() 处理的文件。

默认情况下，这是 CMakeLists.txt。如果设置为其他任何值，则在项目子目录中找不到指定文件时，CMakeLists.txt 将作为回退使用。

注意

此功能旨在供开发者在增量转换期间临时使用，而非用于发布最终产品。当项目文件不是 CMakeLists.txt 时，CMake 总会发出警告。

-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/ 目录，并从头开始重新创建它们。

版本 3.30 变更: 对于先前由 FetchContent 填充并对策略 CMP0168 设置为 NEW 的依赖项，它们在先前运行中留下的时间戳和脚本文件将被删除。因此，下载、更新和补丁步骤将被强制重新执行。

-L[A][H]¶

列出非高级缓存变量。

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

-LR[A][H] <regex>¶

在版本 3.31 中添加。

显示特定的非高级缓存变量

显示 CMake CACHE 中与给定正则表达式匹配的既非 INTERNAL 也非 ADVANCED 的变量。如果指定了 A，它还将显示高级变量。如果指定了 H，它还将显示每个变量的帮助信息。

-N¶

仅查看模式。

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

--graphviz=<file>¶

生成依赖关系的 Graphviz 图

此选项生成一个 Graphviz 输入文件，其中将包含项目中所有的库和可执行文件依赖关系，展示项目中目标之间的依赖关系，以及链接的外部库。

当使用 --graphviz=foo.dot 选项运行 CMake 时，它会产生

一个 foo.dot 文件，展示项目中的所有依赖关系
为每个目标生成一个 foo.dot.<target> 文件，展示它所依赖的其他目标
为每个目标生成一个 foo.dot.<target>.dependers 文件，展示其他哪些目标依赖于它

这些 .dot 文件可以使用 Graphviz 包中的 dot 命令转换为图像

dot -Tpng -o foo.png foo.dot

版本 3.10 新增: 不同的依赖类型 PUBLIC、INTERFACE 和 PRIVATE 分别表示为实线、虚线和点线边。

特定于 Graphviz 支持的变量

生成的图表可能非常庞大。生成的图表的外观和内容可以使用 CMakeGraphVizOptions.cmake 文件进行控制。系统首先在 CMAKE_BINARY_DIR 中搜索此文件，然后在 CMAKE_SOURCE_DIR 中搜索。如果找到，文件中设置的变量将用于调整生成的 Graphviz 文件的选项。

GRAPHVIZ_GRAPH_NAME¶

图表名称。

必须: 否
默认值: CMAKE_PROJECT_NAME 的值

GRAPHVIZ_GRAPH_HEADER¶

写入 Graphviz 文件顶部的标头。

必须: 否
默认值: "node [ fontsize = "12" ];"

GRAPHVIZ_NODE_PREFIX¶

Graphviz 文件中每个节点的名称前缀。

必须: 否
默认值: "node"

GRAPHVIZ_EXECUTABLES¶

设置为 FALSE 可从生成的图中排除可执行文件。

必须: 否
默认值: TRUE

GRAPHVIZ_STATIC_LIBS¶

设置为 FALSE 可从生成的图中排除静态库。

必须: 否
默认值: TRUE

GRAPHVIZ_SHARED_LIBS¶

设置为 FALSE 可从生成的图中排除共享库。

必须: 否
默认值: TRUE

GRAPHVIZ_MODULE_LIBS¶

设置为 FALSE 可从生成的图中排除模块库。

必须: 否
默认值: TRUE

GRAPHVIZ_INTERFACE_LIBS¶

设置为 FALSE 可从生成的图中排除接口库。

必须: 否
默认值: TRUE

GRAPHVIZ_OBJECT_LIBS¶

设置为 FALSE 可从生成的图中排除对象库。

必须: 否
默认值: TRUE

GRAPHVIZ_UNKNOWN_LIBS¶

设置为 FALSE 可从生成的图中排除未知库。

必须: 否
默认值: TRUE

GRAPHVIZ_EXTERNAL_LIBS¶

设置为 FALSE 可从生成的图中排除外部库。

必须: 否
默认值: TRUE

GRAPHVIZ_CUSTOM_TARGETS¶

设置为 TRUE 可在生成的图中包含自定义目标。

必须: 否
默认值: FALSE

GRAPHVIZ_IGNORE_TARGETS¶

用于从生成的图中排除的目标名称的正则表达式列表。

必须: 否
默认值: 空

GRAPHVIZ_GENERATE_PER_TARGET¶

设置为 FALSE 可不生成针对每个目标的图 foo.dot.<target>。

必须: 否
默认值: TRUE

GRAPHVIZ_GENERATE_DEPENDERS¶

设置为 FALSE 可不生成依赖者图 foo.dot.<target>.dependers。

必须: 否
默认值: TRUE

--system-information [file]¶

转储有关此系统的信息。

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

--print-config-dir¶

在版本 3.31 中添加。

打印用户范围 FileAPI 查询的 CMake 配置目录。

有关更多详细信息，请参阅 CMAKE_CONFIG_DIR。

--log-level=<level>¶

3.16 版新增。

设置日志 <level>。

message() 命令将仅输出指定日志级别或更高级别的消息。有效的日志级别包括 ERROR、WARNING、NOTICE、STATUS（默认）、VERBOSE、DEBUG 或 TRACE。

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

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

版本 3.25 新增: 有关查询当前消息日志级别的方法，请参阅 cmake_language() 命令。

--log-context¶

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

此选项仅开启当前 CMake 运行的上下文显示。为了使上下文显示在所有后续的 CMake 运行中持久化，请改为将 CMAKE_MESSAGE_CONTEXT_SHOW 设置为缓存变量。当给出此命令行选项时，CMAKE_MESSAGE_CONTEXT_SHOW 将被忽略。

--sarif-output=<path>¶

4.0 版本新增。

启用以 SARIF 格式记录 CMake 产生的诊断消息。

将诊断消息写入指定路径的 SARIF 文件。项目也可以将 CMAKE_EXPORT_SARIF 设置为 ON，从而为构建树启用此功能。

--debug-trycompile¶

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

请注意，try_compile() 的某些使用场景可能会使用同一个构建树，如果项目执行了多个 try_compile()，这将限制此选项的有效性。例如，此类使用可能会更改结果，因为先前 try-compile 的产物可能会导致不同的测试不正确地通过或失败。此选项最好仅在调试时使用。

（关于上述说明，try_run() 命令实际上是一个 try_compile()。两者的任何组合都可能存在所描述的潜在问题。）

版本 3.25 新增: 启用此选项后，每个 try-compile 检查都会打印一条日志消息，报告执行检查的目录。

--debug-output¶

将 cmake 置于调试模式。

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

--debug-find¶

在 3.17 版本中添加。

将 cmake 查找命令置于调试模式。

在 cmake 运行期间向标准错误输出额外的查找调用信息。输出旨在供人工阅读，而非解析。有关调试项目中更局部部分的信息，请参阅 CMAKE_FIND_DEBUG_MODE 变量。

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

在版本 3.23 中添加。

在执行 find_package(<pkg>) 调用时，将 cmake 查找命令置于调试模式，其中 <pkg> 是给定逗号分隔列表中的一个条目，区分大小写。

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

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

在版本 3.23 中添加。

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

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

--trace¶

将 cmake 置于跟踪模式。

打印所有已完成调用及其来源的跟踪信息。

--trace-expand¶

将 cmake 置于跟踪模式。

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

--trace-format=<format>¶

在 3.17 版本中添加。

将 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
}
成员是

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

行
在 file 中函数调用开始的行。

line_end
如果函数调用跨越多行，此字段将设置为函数调用结束的行。如果函数调用跨越单行，此字段将未设置。此字段在 json-v1 格式的次版本 2 中添加。

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

cmd
所调用的函数名称。

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

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

frame
在当前正在处理的 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¶: 在 3.24 版本中添加。

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

--link-no-warning-as-error¶: 4.0 版本新增。

忽略目标属性 LINK_WARNING_AS_ERROR 和变量 CMAKE_LINK_WARNING_AS_ERROR，防止警告在链接时被视为错误。

--profiling-output=<path>¶: 在 3.18 版本中新增。

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

--profiling-format=<file>¶

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

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

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

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

从 CMakePresets.json 和 CMakeUserPresets.json 文件读取 预设 (preset)，这些文件必须位于与顶层 CMakeLists.txt 文件相同的目录中。预设可以指定生成器、构建目录、变量列表以及传递给 CMake 的其他参数。CMakePresets.json 或 CMakeUserPresets.json 中至少必须存在一个。CMake GUI 也识别并支持 CMakePresets.json 和 CMakeUserPresets.json 文件。有关这些文件的完整详细信息，请参阅 cmake-presets(7)。

预设在所有其他命令行选项之前被读取，尽管 -S 选项可用于指定包含 CMakePresets.json 和 CMakeUserPresets.json 文件的源码目录。如果未给定 -S，则假定当前目录为顶层源码目录，且必须包含预设文件。所选预设指定的选项（变量、生成器等）都可以通过在命令行上手动指定它们来覆盖。例如，如果预设将名为 MYVAR 的变量设置为 1，但用户通过 -D 参数将其设置为 2，则值 2 优先。

--list-presets[=<type>]¶: 列出指定 <type> 的可用预设。<type> 的有效值为 configure、build、test、package 或 all。如果省略 <type>，则假定为 configure。除非使用 -S 选项指定不同的顶层源码目录，否则当前工作目录必须包含 CMake 预设文件。

--debugger¶

启用 CMake 语言的交互式调试。CMake 在 --debugger-pipe 命名的管道上公开了一个调试接口，该接口符合调试适配器协议 (Debug Adapter Protocol) 规范，并进行了以下修改。

initialize 响应包含一个名为 cmakeVersion 的附加字段，用于指定正在调试的 CMake 版本。

调试器 initialize 响应¶

{
  "cmakeVersion": {
    "major": 3,
    "minor": 27,
    "patch": 0,
    "full": "3.27.0"
  }
}

成员是

主要版本: 指定主版本号的整数。
次要版本: 指定次版本号的整数。
patch: 指定补丁版本号的整数。
full: 指定完整 CMake 版本的字符串。

--debugger-pipe <pipe name>, --debugger-pipe =<pipe name>¶: 用于调试器通信的管道（在 Windows 上）或域套接字（在 Unix 上）名称。

--debugger-dap-log <log path>, --debugger-dap-log =<log path>¶: 将所有调试器通信记录到指定文件。

构建项目¶

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

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

这通过以下选项抽象了原生构建工具的命令行接口

--build <dir>¶: 要构建的项目二进制目录。这是必需的（除非指定了预设），并且必须位于第一位。

--preset <preset>, --preset =<preset>¶: 使用构建预设来指定构建选项。除非在 --build 之后指定了目录，否则项目二进制目录将从 configurePreset 键中推断得出。当前工作目录必须包含 CMake 预设文件。有关更多详细信息，请参阅 preset。

版本 4.3 变更: cmake --build 现在支持同时指定构建目录和预设。

--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 --build 在某些生成器上有特殊行为

Xcode

Added in version 4.1: 如果第三方工具在 CMake 生成的 .xcodeproj 旁边写入了 .xcworkspace，则 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 变量的值。

此选项的主要目的是允许安装到任意位置。这常见于某些安装和打包工作流中。它类似于在安装阶段选择安装目录。例如，在 Windows 上，用户可以选择项目的目标文件夹。

注意

当项目使用 GNUInstallDirs 模块时，会有一些特殊情况，它们是根据配置阶段 CMAKE_INSTALL_PREFIX 变量的值来评估的。即使在安装期间使用了替代前缀，这些结果也会持续存在。

--strip¶: 安装前进行剥离（Strip）。

-v, --verbose¶

启用详细输出。

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

-j <jobs>, --parallel <jobs>¶: 在版本 3.31 中添加。

使用指定数量的任务并行安装。仅在启用了 INSTALL_PARALLEL 时可用。CMAKE_INSTALL_PARALLEL_LEVEL 环境变量指定了当未提供此选项时的默认并行级别。

运行 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 获取命令汇总。

可用命令如下

bin2c [<options>...] [--] [<input-file> [<output-file>]]¶

Added in version 4.3.

将二进制文件转换为 C 数组。如果未指定输入文件或为 -，则从标准输入读取而非文件。如果未指定输出文件或为 -，则写入标准输出而非文件。

默认情况下，这仅打印字节。可以使用 --template-file 参数添加封闭文本。您还可以 #include 来自另一个文件的字节，作为 C23 和 C++26 的 #embed 指令的即插即用替代品。

unsigned char my_bytes[] = {
/* #embed "bin2c_input.bin" */
#include "bin2c_output.c.txt"
};

--signed¶: 将字节打印为有符号整数，而非无符号。

--decimal¶: 将字节打印为十进制，而非十六进制。

--trailing-comma¶: 在最后一个字节后附加尾随逗号（默认不包含）。

--template-file <template-file>¶

根据模板文件进行格式化。模板文件包含用于数组及可选长度（将是非负十进制整数）的占位符。此类占位符在开始和结束处用 @ 括起来。此功能类似于以 @ONLY 参数调用的 configure_file()，但只会替换数组和长度占位符，其他任何占位符将保持原样。

潜在模板文件的示例

unsigned char my_bytes[] = {@array@};

size_t length = @length@;

数组占位符在模板文件中最多出现一次。长度占位符可在数组占位符之后出现零次或多次，但不得在其之前。

请注意，长度是打印的元素数量，如果使用了除 unsigned char 之外的类型，可能与生成的数组的 sizeof 不匹配。

--template-array-placeholder <placeholder-name>¶: 指定模板文件中数组占位符的名称。默认设置为 array。

--template-length-placeholder <placeholder-name>¶: 指定模板文件中长度占位符的名称。默认设置为 length。

capabilities¶

3.7 版本中新增。

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

版本

包含版本信息的 JSON 对象。键为

string: 由 cmake --version 显示的完整版本字符串。
主要版本: 整数形式的主要版本号。
次要版本: 整数形式的次要版本号。
patch: 整数形式的补丁级别。
suffix: cmake 版本后缀字符串。
isDirty: 如果 cmake 构建来自未清理（dirty）的代码树，则设置为 true 的布尔值。

生成器

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

名称: 包含生成器名称的字符串。
toolsetSupport: 如果生成器支持工具集（toolsets），则为 true，否则为 false。
platformSupport: 如果生成器支持平台（platforms），则为 true，否则为 false。
supportedPlatforms: 3.21 版本新增。

当生成器支持通过 CMAKE_GENERATOR_PLATFORM (-A ...) 指定平台时可能出现的可选成员。其值是已知支持的平台列表。
extraGenerators: 包含与该生成器兼容的所有额外生成器的字符串列表。

fileApi

当 cmake-file-api(7) 可用时出现的可选成员。该值为一个包含一个成员的 JSON 对象

requests

包含零个或多个支持的 file-api 请求的 JSON 数组。每个请求都是一个包含以下成员的 JSON 对象

种类: 指定支持的对象种类之一。
版本: 一个 JSON 数组，其元素每个都是包含 major 和 minor 成员的 JSON 对象，指定非负整数版本组件。

serverMode

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

tls

在 3.25 版本中新增。

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

debugger

在 3.27 版本中新增。

如果支持 --debugger 模式，则为 true，否则为 false。

cat [--] <files>...¶

在 3.18 版本中新增。

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

--¶: 在 3.24 版本中添加。

增加了对双短横线参数 -- 的支持。这个简单的 cat 实现不支持任何选项，因此使用以 - 开头的选项会导致错误。如果文件名以 - 开头，请使用 -- 指示选项结束。

Added in version 3.29: 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，则假定最后一个参数是 <destination>。不支持通配符。copy 确实会跟随符号链接。这意味着它不会复制符号链接本身，而是复制它们指向的文件或目录。

Added in version 3.5: 对多个输入文件的支持。

Added in version 3.26: 对 -t 参数的支持。

copy_directory <dir>... <destination>¶: 将 <dir>... 目录的内容复制到 <destination> 目录。如果 <destination> 目录不存在，则会创建它。copy_directory 会跟随符号链接。

Added in version 3.5: 对多个输入目录的支持。

Added in version 3.15: 该命令现在在源目录不存在时失败。以前它通过创建一个空的空目标目录而成功。

copy_directory_if_different <dir>... <destination>¶

3.26 版新增。

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

copy_directory_if_different 会跟随符号链接。当源目录不存在时，该命令失败。

copy_directory_if_newer <dir>... <destination>¶

版本 4.2 中添加。

如果源文件比目标文件更新（基于文件时间戳），则将 <dir>... 目录的内容复制到 <destination> 目录。如果 <destination> 目录不存在，则会创建它。

copy_directory_if_newer 会跟随符号链接。当源目录不存在时，该命令失败。这比 copy_directory_if_different 更快，因为它只比较文件时间戳，而不是文件内容。

copy_if_different <file>... <destination>¶: 如果文件已更改，则将其复制到 <destination>（可以是文件或目录）。如果指定了多个文件，则 <destination> 必须是目录且必须存在。copy_if_different 会跟随符号链接。

Added in version 3.5: 对多个输入文件的支持。

copy_if_newer <file>... <destination>¶: 版本 4.2 中添加。

如果源文件比目标文件更新（基于文件时间戳），则将文件复制到 <destination>（可以是文件或目录）。如果指定了多个文件，则 <destination> 必须是目录且必须存在。copy_if_newer 会跟随符号链接。这比 copy_if_different 更快，因为它只比较文件时间戳，而不是文件内容。

create_symlink <old> <new>¶: 创建指向 <old> 的符号链接 <new>。

Added in version 3.13: 对在 Windows 上创建符号链接的支持。

注意

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

create_hardlink <old> <new>¶: 3.19 版本新增。

创建指向 <old> 的硬链接 <new>。

注意

创建 <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> 目录。如有必要，同时创建父目录。如果目录已存在，它将被静默忽略。

Added in version 3.5: 对多个输入目录的支持。

md5sum <file>...¶

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

351abe79cd3800b38cdfb25d45015a15  file1.txt
052f86c15bbde68af55c7f7b340ab639  file2.txt