cmake(1)

cmake(1)

Synopsis

Generate a Project Buildsystem
 cmake [<options>] <path-to-source>
 cmake [<options>] <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>]

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

Description

cmake可执行文件是跨平台构建系统生成器cmake的命令行界面。上述概要列出了该工具可以执行的各种操作，如以下各节所述。
要使用CMake构建软件项目，请生成项目构建系统。可以选择使用cmake构建项目、安装项目或直接运行相应的构建工具（例如make）。cmake还可以用于查看帮助。
其他操作是供软件开发人员使用的，他们用CMake语言编写脚本来支持他们的构建。
有关可以代替cmake使用的图形用户界面，请参见ccmake和cmake gui。有关CMake测试和打包工具的命令行界面，请参阅ctest和cpack。
有关CMake的更多信息，请参阅本手册末尾的链接。

Introduction to CMake Buildsystems

构建系统描述了如何使用构建工具从项目的源代码构建项目的可执行文件和库，以实现过程的自动化。例如，构建系统可以是用于命令行生成工具的生成文件，也可以是用于集成开发环境（IDE）的项目文件。为了避免维护多个这样的构建系统，项目可以使用用CMake语言编写的文件抽象地指定其构建系统。从这些文件中，CMake通过称为生成器的后端为每个用户本地生成一个首选构建系统。
要使用CMake生成构建系统，必须选择以下选项：
Source Tree
包含项目提供的源文件的顶级目录。该项目使用cmake语言（7）手册中描述的文件指定其构建系统，从名为CMakeLists.txt的顶级文件开始。这些文件指定了构建目标及其依赖关系，如cmake-buildsystem（7）手册中所述。
Build Tree
构建系统文件和构建输出工件（如可执行文件和库）将存储在其中的顶级目录。CMake将写入CMakeCache。txt文件，将目录标识为构建树并存储持久信息，如构建系统配置选项。
要维护原始源代码树，请使用单独的专用构建树执行源代码外构建。也支持将构建树放置在与源树相同的目录中的源内构建，但不建议这样做。
Generator
这将选择要生成的构建系统的类型。有关所有发电机的文档，请参阅cmake发电机（7）手册。运行cmake-help以查看本地可用的生成器列表。可以选择使用下面的-G选项指定生成器，或者只接受当前平台的默认CMake选择。
当使用其中一个命令行构建工具生成器时，CMake希望编译器工具链所需的环境已经在shell中配置。当使用IDE构建工具生成器之一时，不需要特定的环境。

Generate a Project Buildsystem

使用以下命令签名之一运行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>
使用＜path to build＞作为构建树，使用＜path-to source＞作为源树。指定的路径可以是绝对路径，也可以是相对于当前工作目录的路径。源树必须包含CMakeLists。txt文件。如果生成树不存在，将自动创建该树。例如：

$ cmake -S src -B build

在所有情况下，＜options＞可以是以下选项中的零个或多个。
生成构建系统后，可以使用相应的本地构建工具来构建项目。例如，在使用Unix Makefiles生成器之后，可以直接运行make：

$ make
$ make install

或者，可以使用cmake通过自动选择并调用适当的本地构建工具来构建项目。

Options

-S <path-to-source>
要生成的CMake项目的根目录的路径。
-B <path-to-build>
CMake将用作生成目录根目录的目录路径。
如果目录不存在，CMake将创建它。
-C <initial-cache>
预加载脚本以填充缓存。
当CMake首次在空构建树中运行时，它会创建一个CMakeCache.txt文件，并用项目的自定义设置填充它。此选项可用于指定在第一次通过项目的CMake列表文件之前从中加载缓存项的文件。加载的条目优先于项目的默认值。给定的文件应该是包含使用CACHE选项的set（）命令的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>。
-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变量。
-Wno-dev
抑制开发人员警告。
取消针对CMakeLists.txt文件作者的警告。默认情况下，这也将关闭弃用警告。
-Wdev
启用开发人员警告。
启用针对CMakeLists.txt作者的警告文件。默认情况下，这也将启用弃用警告
-Werror=dev
生成开发人员警告错误。
针对CMakeLists.txt文件错误的作者发出警告。默认情况下，这也会将不推荐的警告作为错误打开。
略…
--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>
设置日志级别。
message（）命令将只输出指定日志级别或更高级别的消息。默认日志级别为STATUS。
要在CMake运行之间保持日志级别，请将CMAKE_MESSAGE_LOG_LEVEL设置为缓存变量。如果同时给定了命令行选项和变量，则命令行选项优先。
出于向后兼容性的原因，–loglevel也被接受为此选项的同义词。
--log-context
启用message（）命令，输出附加到每条消息的上下文。
此选项启用仅显示当前CMake运行的上下文。要使显示所有后续CMake运行的上下文持久，请将CMAKE_MESSAGE_CONTEXT_SHOW设置为缓存变量。当给定此命令行选项时，将忽略CMAKE_MESSAGE_CONTEXT_SHOW。
--debug-trycompile
不要删除try_comple（）生成树。一次只能在一个try_comple（）上使用。
不要删除为try_comple（）调用创建的文件和目录。这在调试失败的try_compiles时很有用。但是，它可能会更改尝试编译的结果，因为以前尝试编译的旧垃圾可能会导致不同的测试错误通过或失败。此选项最好用于一次一次的尝试编译，并且仅在调试时使用。
--debug-find
将cmake-find命令置于调试模式。
在cmake运行到标准错误期间打印额外的查找调用信息。输出是为人类消费而非解析而设计的。另请参见CMAKE_FIND_DEBUG_MODE变量，以调试项目的更局部的部分。
--trace
将cmake置于跟踪模式。
打印所有拨打的电话和来自何处的电话记录。

Build a Project

CMake提供了一个命令行签名来构建已经生成的项目二叉树
cmake --build <dir> [<options>] [-- <build-tool-options>]

Install a Project

CMake提供命令行签名来安装已生成的项目二进制树：

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

这可以在生成项目后使用，以便在不使用生成的生成系统或本机生成工具的情况下运行安装。选项包括：
--install <dir>

要安装的项目二进制目录。这是必需的，必须是第一个。
--config <cfg>
对于多配置生成器，请选择configuration＜cfg＞。
--component <comp>
基于组件的安装。仅安装组件。