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 的命令行接口。上面的 概要 列出了该工具可以执行的各种操作，如下面的章节所述。

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

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

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

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

CMake 构建系统的简介

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

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

源代码树

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

构建树

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

为了维护原始的源代码树，请通过使用单独的专用构建树执行源外构建。源内构建（其中构建树放置在与源代码树相同的目录中）也受支持，但不建议使用。

生成器

这将选择要生成的构建系统的类型。有关所有生成器的文档，请参阅 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	build
cmake -B build src	src	build
cmake -B build -S src	src	build
cmake src	src	cwd
cmake build (已存在)	加载	build
cmake -S src	src	cwd
cmake -S src build	src	build
cmake -S src -B build	src	build

版本 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() 命令（使用 CACHE 选项）的 CMake 脚本，而不是缓存格式文件。

脚本中对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 参数设置了相同的变量，则 -D 参数将优先，无论顺序如何，因为非 FORCE set(... CACHE ...) 调用的特性。

-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>

版本 3.21 中新增。

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

--install-prefix <directory>

版本 3.21 中新增。

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

-Wno-dev

抑制开发人员警告。

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

-Wdev

启用开发人员警告。

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

-Wdeprecated

启用已弃用功能警告。

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

-Wno-deprecated

抑制已弃用功能警告。

抑制针对 CMakeLists.txt 文件作者的已弃用功能使用警告。

-Werror=<what>

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

dev

将开发人员警告视为错误。

将针对 CMakeLists.txt 文件作者的警告视为错误。默认情况下，这还会将弃用警告视为错误。

deprecated

将已弃用宏和函数警告视为错误。

将针对 CMakeLists.txt 文件作者的已弃用宏和函数使用警告视为错误。

-Wno-error=<what>

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

dev

将针对 CMakeLists.txt 文件作者的警告不视为错误。默认情况下，这还会将弃用警告不视为错误。

deprecated

将针对 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 图，有关更多信息，请参阅 CMakeGraphVizOptions。

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

--system-information [file]

转储有关此系统的信息。

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

--print-config-dir

版本 3.31 中新增。

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

有关更多详细信息，请参阅 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。

--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 find 命令置于调试模式。

在 cmake 运行期间将额外的 find 调用信息打印到标准错误。输出设计供人类使用，而不是供解析。有关调试项目更本地部分的信息，另请参阅 CMAKE_FIND_DEBUG_MODE 变量。

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

版本 3.23 中新增。

在运行 find_package(<pkg>) 的调用下时，将 cmake find 命令置于调试模式，其中 <pkg> 是给定逗号分隔的区分大小写的包名称列表中的条目。

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

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

版本 3.23 中新增。

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

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

--trace

将 cmake 置于跟踪模式。

打印所有调用的跟踪以及调用来源。

--trace-expand

将 cmake 置于跟踪模式。

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

--trace-format=<format>

版本 3.17 中新增。

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

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

human

以人类可读的格式打印每行跟踪信息。这是默认格式。

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 源文件的完整路径。

line

函数调用开始的 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
  }
}

成员包括

version

指示 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，防止警告在编译时被视为错误。

--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 命名的管道上公开调试接口，该接口符合 调试适配器协议 规范，并进行了以下修改。

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

调试器初始化响应

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

成员包括

major

指定主版本号的整数。

minor

指定次版本号的整数。

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>

使用构建预设来指定构建选项。项目二进制目录从 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环境变量，则可以省略此选项。

-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 以获取命令摘要。

可用的命令是

capabilities

版本3.7中添加。

以JSON格式报告cmake功能。输出是一个JSON对象，包含以下键

version

一个包含版本信息的JSON对象。键是

字符串

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

major

主版本号（整数形式）。

minor

次版本号（整数形式）。

patch

补丁级别（整数形式）。

后缀

cmake版本后缀字符串。

isDirty

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

生成器

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

名称

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

toolsetSupport

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

platformSupport

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

supportedPlatforms

版本 3.21 中新增。

当生成器支持通过CMAKE_GENERATOR_PLATFORM（-A ...）指定平台时，可能存在的可选成员。该值是已知支持的平台列表。

extraGenerators

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

fileApi

当cmake-file-api(7)可用时，可能存在的可选成员。该值是一个JSON对象，包含一个成员

请求

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

种类

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

version

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

服务器模式

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

TLS

版本3.25中添加。

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

调试器

版本3.27中添加。

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

cat [--] <files>...

在版本 3.18 中添加。

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

--

版本 3.24 中新增。

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

版本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 遵循符号链接。这意味着它不会复制符号链接，而是复制它指向的文件或目录。

版本 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>

创建名为 <old> 的符号链接 <new>。

版本 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> 目录。如有必要，还会创建父目录。如果目录已存在，则会静默忽略。

版本 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 中新增。

休眠 <number> 秒。 <number> 可以是浮点数。由于启动/停止 CMake 可执行文件的开销，实际最小值约为 0.1 秒。这在 CMake 脚本中很有用，可以插入延迟。

# Sleep for about 0.5 seconds
execute_process(COMMAND ${CMAKE_COMMAND} -E sleep 0.5)

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>...]

运行 <command> 并显示经过的时间（包括 CMake 前端开销）。

版本 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 注册表值。

运行 Find-Package 工具

CMake 为基于 Makefile 的项目提供了一个类似 pkg-config 的助手。

cmake --find-package [<options>]

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

注意

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

运行工作流预设

版本3.25中添加。

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

cmake --workflow <options>

选项如下：

--workflow

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

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

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

3.31版本中已更改: 当紧跟在--workflow选项之后时，可以省略--preset参数，只需提供<preset>名称即可。这意味着以下语法有效

$ cmake --workflow my-preset

--list-presets

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

--fresh

执行构建树的新配置，其效果与cmake --fresh相同。

查看帮助

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

cmake --help[-<topic>]

以下选项之一

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

显示程序名称/版本横幅并退出。如果给出，则输出将打印到名为<file>的文件中。

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

打印使用信息并退出。

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

--help <keyword> [<file>]

打印一个 CMake 关键字的帮助信息。

<keyword>可以是属性、变量、命令、策略、生成器或模块。

以人类可读的文本格式打印<keyword>的相关手册条目。如果给出，则输出将打印到名为<file>的文件中。

3.28版本中已更改: 在 CMake 3.28 之前，此选项仅支持命令名称。

--help-full [<file>]

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

所有手册都以人类可读的文本格式打印。如果给出，则输出将打印到名为<file>的文件中。

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

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

指定的手册以人类可读的文本格式打印。如果给出，则输出将打印到名为<file>的文件中。

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

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

该列表包含所有可以使用--help-manual选项后跟手册名称获取帮助的手册。如果给出，则输出将打印到名为<file>的文件中。

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

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

cmake-commands(7)手册条目<cmd>以人类可读的文本格式打印。如果给出，则输出将打印到名为<file>的文件中。

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

列出可以使用帮助的命令并退出。

该列表包含所有可以使用--help-command选项后跟命令名称获取帮助的命令。如果给出，则输出将打印到名为<file>的文件中。

--help-commands [<file>]

打印 cmake-commands 手册并退出。

cmake-commands(7)手册以人类可读的文本格式打印。如果给出，则输出将打印到名为<file>的文件中。

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

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

cmake-modules(7)手册条目<mod>以人类可读的文本格式打印。如果给出，则输出将打印到名为<file>的文件中。

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

列出可以使用帮助的模块并退出。

该列表包含所有可以使用--help-module选项后跟模块名称获取帮助的模块。如果给出，则输出将打印到名为<file>的文件中。

--help-modules [<file>]

打印 cmake-modules 手册并退出。

cmake-modules(7)手册以人类可读的文本格式打印。如果给出，则输出将打印到名为<file>的文件中。

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

打印一个策略的帮助信息并退出。

针对 <cmp> 的 cmake-policies(7) 手册条目将以人类可读的文本格式打印。如果提供了名称为 <file> 的文件，则输出将打印到该文件中。

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

列出可获取帮助的策略并退出。

该列表包含所有可以使用 --help-policy 选项后跟策略名称来获取帮助的策略。如果提供了名称为 <file> 的文件，则输出将打印到该文件中。

--help-policies [<file>]

打印 cmake-policies 手册并退出。

将 cmake-policies(7) 手册以人类可读的文本格式打印。如果提供了名称为 <file> 的文件，则输出将打印到该文件中。

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

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

针对 <prop> 的 cmake-properties(7) 手册条目将以人类可读的文本格式打印。如果提供了名称为 <file> 的文件，则输出将打印到该文件中。

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

列出可获取帮助的属性并退出。

该列表包含所有可以使用 --help-property 选项后跟属性名称来获取帮助的属性。如果提供了名称为 <file> 的文件，则输出将打印到该文件中。

--help-properties [<file>]

打印 cmake-properties 手册并退出。

将 cmake-properties(7) 手册以人类可读的文本格式打印。如果提供了名称为 <file> 的文件，则输出将打印到该文件中。

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

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

针对 <var> 的 cmake-variables(7) 手册条目将以人类可读的文本格式打印。如果提供了名称为 <file> 的文件，则输出将打印到该文件中。

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

列出可获取帮助的变量并退出。

该列表包含所有可以使用 --help-variable 选项后跟变量名称来获取帮助的变量。如果提供了名称为 <file> 的文件，则输出将打印到该文件中。

--help-variables [<file>]

打印 cmake-variables 手册并退出。

将 cmake-variables(7) 手册以人类可读的文本格式打印。如果提供了名称为 <file> 的文件，则输出将打印到该文件中。

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

cmake <source-dir> --list-presets

返回值（退出代码）

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

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

另请参阅

以下资源可用于获取有关如何使用 CMake 的帮助

主页

https://cmake.com.cn

学习有关 CMake 的主要起点。

在线文档和社区资源

https://cmake.com.cn/documentation

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

讨论论坛

https://discourse.cmake.org

讨论论坛承载有关 CMake 的讨论和问题。