cmake：命令行工具cmake
概要
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>]
描述
cmake可执行文件是跨平台构建系统生成器cmake的命令行界面。上面的概要列出了工具可以执行的各种操作，如下面各节所述。
要使用 CMake 构建软件项目，请参考目录【生成项目构建系统】。
可以选择使用 cmake 来【构建项目】、【安装项目】或直接运行相应的构建工具（例如 make）。 cmake 也可用于【查看帮助】。
其他操作旨在供软件开发人员使用 CMake language编写脚本来支持他们的构建。
有关可用于代替 cmake 的图形用户界面，请参阅 ccmake 和 cmake-gui。 有关 CMake 测试和打包工具的命令行界面，请参阅 ctest 和 cpack。
有关 CMake 的更多信息，【另请参阅】本手册末尾的链接。
CMake构建系统简介
[构建系统]描述了如何使用构建工具从源代码构建项目的可执行文件和库，从而实现该过程的自动化。举个例子
- 构建系统可以是与命令行make工具一起使用的Makefile
- 也可以是集成开发环境(IDE)的项目文件
为了避免维护多个这样的构建系统，项目可以使用CMake语言编写的文件抽象地指定其构建系统。从这些文件中，CMake通过一个名为generator的后端在本地为每个用户生成一个首选[构建系统]。
要用CMake生成一个构建系统，必须选择以下选项:
- 源码树
- 包含项目提供的源文件的顶级目录。
- 该项目使用cmake-language(7)手册中描述的文件指定其构建系统，从名为CMakeLists.txt的顶级文件开始。
- 这些文件指定构建目标和它们的依赖项，如cmake-buildsystem(7)手册所述。
- 构建树
- 存储构建系统文件和构建输出工件（如可执行文件和库）的顶层目录。
- CMake将编写一个CMakeCache.txt文件，以将目录标识为构建树，并存储持久性信息，如buildsystem配置选项。
- 要维护原始的源代码树，请使用单独的专用生成树执行源代码外生成。也支持将生成树放置在与源树相同的目录中的源内生成，但不鼓励这样做。
- Generator
- 这选择了要生成的构建系统的类型。
- 请参阅cmake-generators(7)手册，了解所有生成器的文档。
- 运行
cmake --help查看本地可用的生成器列表。 - 可以选择使用下面的
-G选项来指定一个生成器，或者简单地接受当前平台的默认CMake选项。
当使用命令行构建工具生成器时，CMake期望编译器工具链所需的环境已经在shell中配置好了。当使用IDE构建工具生成器时，不需要特定的环境。
生成项目构建系统
使用以下命令签名之一运行CMake来指定源代码和构建树并生成一个构建系统:
cmake [
- 使用当前工作目录作为构建树，并使用作为源树。
- 指定的路径可以是绝对的，也可以是相对于当前工作目录的。
- 源树必须包含CMakeLists.txt文件，不能包含CMakeCache.txt文件，因为后者标识了一个现有的构建树。
- 例如:
$ mkdir build ; cd build
$ cmake ../src
cmake [
- 使用
- 指定的路径可以是绝对的，也可以是相对于当前工作目录的。
- 例如:
$ cd build
$ cmake .
cmake [
- 使用< path to build>作为构建树，使用< path to source>作为源树。
- 指定的路径可以是绝对路径，也可以是相对于当前工作目录的路径。
- 源树必须包含CMakeLists.txt文件。如果生成树不存在，则会自动创建它。
- 例如：
$ cmake -S src -B build
在所有情况下，可以是下面的0个或多个【options】。
在生成构建系统之后，可以使用相应的本地构建工具来构建项目。例如，在使用Unix Makefiles生成器后，可以直接运行make:
$ make
$ make install
或者，可以使用cmake自动选择并调用适当的本地构建工具来构【构建项目】。
Options
-S
- 要构建的CMake项目的根目录的路径。
-B
- CMake将用作构建目录根目录的路径。
- 如果目录不存在，CMake将创建它。
-C
- 预加载一个脚本来填充缓存。
- 当CMake第一次在空生成树中运行时，它会创建一个CMakeCache.txt文件，并用项目的可自定义设置填充该文件。
- 此选项可用于指定在第一次通过项目的CMake listfiles之前从中加载缓存项的文件。加载的条目优先于项目的默认值。
- 给定的文件应该是一个CMake脚本，其中包含使用CACHE选项的set()命令，而不是一个CACHE格式的文件。
-D :
- 创建或更新CMake缓存项。
- 当CMake第一次在空生成树中运行时，它会创建一个CMakeCache.txt文件，并用项目的可自定义设置填充该文件。此选项可用于指定优先于项目默认值的设置。可以根据需要对任意多个缓存条目重复该选项。
- 如果给定
:部分，则它必须是set()命令文档为其缓存签名指定的类型之一。 - 如果省略了
:部分，那么如果条目不存在且已经存在类型，则将不使用类型创建条目。 - 如果项目中的命令将类型设置为PATH或FILEPATH，则
- 此选项也可以作为单个参数提供：
-D:或= -D=。
-U
- 从CMake CACHE中删除匹配的条目。
- 此选项可用于从CMakeCache.txt文件中删除一个或多个变量，使用*和?都受支持。该选项可以对任意多个CACHE条目重复使用。
- 小心使用，你可以使你的CMakeCache.txt不起作用。
-G
- 指定build system generator.
- CMake可能在某些平台上支持多个本机构建系统。生成器负责生成特定的构建系统。可能的生成器名称在cmake-generators(7)手册中指定。
- 如果没有指定，CMake检查CMAKE_GENERATOR环境变量，否则返回内置的默认选择。
-T
- 生成器的工具集规范（如果支持）。
- 一些CMake生成器支持一个工具集规范来告诉本机构建系统如何选择编译器。详细信息请参见CMAKE_GENERATOR_TOOLSET变量。
-A
- 如果生成器支持，请指定平台名称。
- 有些CMake生成器支持给原生构建系统一个平台名来选择编译器或SDK。详细信息请参见CMAKE_GENERATOR_PLATFORM变量。
-Wno-dev
- 抑制开发人员警告。
- 禁止对CMakeLists.txt文件的作者发出警告。默认情况下，这也将关闭弃用警告。
-Wdev
- 启用开发人员警告。
- 启用针对CMakeLists.txt文件作者的警告。默认情况下，这也会打开弃用警告。
-Wno-error=dev
- 对开发人员发出警告而不是错误。
- 对CMakeLists.txt文件的作者发出警告，而不是错误。默认情况下，这也会将已弃用的警告作为错误关闭。
-Wdeprecated
- 启用不推荐使用的功能警告。
- 启用针对不推荐使用的功能的警告，这些功能针对CMakeLists.txt文件的作者。
-Wno-deprecated
- 取消不推荐使用的功能警告。
- 禁止使用针对CMakeLists.txt文件作者的已弃用功能的警告。
-Werror=deprecated
- 生成不推荐使用的宏和函数警告错误。
- 对不推荐使用的宏和函数（针对CMakeLists.txt文件的作者）发出警告，并指出错误。.
-Wno-error=deprecated
- 使不推荐使用的宏和函数出现警告而不是错误。
- 对不推荐使用的宏和函数发出警告，这些宏和函数是针对CMakeLists.txt文件的作者，而不是针对错误
-L[A][H]·
-
列出非高级缓存变量。
-
List CACHE variables将运行CMake并列出CMake缓存中未标记为内部()(INTERNAL)或高级(ADVANCED)的所有变量。
-
这将有效地显示当前的CMake设置，然后可以使用-D选项进行更改。
-
更改某些变量可能会导致创建更多的变量。
-
如果指定了A，那么它还将显示高级变量。
-
如果指定了H，它还将显示每个变量的帮助。
-N
- 视图模式。
- 只加载缓存。不要实际运行配置和生成步骤。
--graphviz=[file]
- 生成依赖的graphviz，参见CMakeGraphVizOptions了解更多。
- 生成一个graphviz输入文件，该文件将包含项目中的所有库和可执行依赖项。更多细节请参见CMakeGraphVizOptions的文档。
--system-information [file]
- 转储此系统信息。
- 转储关于当前系统的大量信息。如果从CMake项目的二叉树顶部运行，它将转储额外的信息，如缓存，日志文件等。
--loglevel=
- 设置日志级别。
- message()命令只输出指定日志级别或更高级别的消息。缺省情况下，日志级别为STATUS。
--debug-trycompile
- 不要删除try_compile()构建树。一次只对一个try_compile()有用。
- 不要删除为try_compile()调用创建的文件和目录。这在调试失败的try_compiles时很有用。但是，它可能会将try-compile的结果更改为旧垃圾，可能导致不同的测试通过或错误失败。此选项最好用于一次只进行一次试编译，且仅在调试时使用。
--debug-output
- 将cmake置于调试模式。
- 在cmake运行期间打印额外的信息，就像使用message(SEND_ERROR)调用进行堆栈跟踪一样。
--trace
- 将cmake置于跟踪模式。
- 打印出所有的调用记录和调用地点。
--trace-expand
- 将cmake置于跟踪模式。
- 类似–trace，但是扩展了变量。
--trace-source=
- 将cmake置于跟踪模式，但只输出指定文件的行。
- 允许有多个选项。
--warn-uninitialized
- 对未初始化的值发出警告。
- 当使用未初始化的变量时，打印警告。
--warn-unused-vars
- 警告未使用的变量。
- 查找已声明或设置但未使用的变量。
--no-warn-unused-cli
- 不要对命令行选项发出警告。
- 不要找到在命令行上声明但没有使用的变量。
--check-system-vars
- 查找系统文件中变量使用的问题。
- 通常，只在CMAKE_SOURCE_DIR和CMAKE_BINARY_DIR中搜索未使用和未初始化的变量。这个标志也告诉CMake对其他文件发出警告。
构建项目
CMake提供了一个命令行签名来构建已经生成的项目二叉树
cmake --build
这将使用以下选项抽象本机构建工具的命令行界面：
--install- 要安装的项目二进制目录。这是必须的，也必须是第一。
--config- 对于多配置生成器，选择配置
- 对于多配置生成器，选择配置
--component- 基于组件的安装。仅安装组件
- 基于组件的安装。仅安装组件
--prefix- 覆盖安装前缀CMAKE_INSTALL_PREFIX。
--strip- Strip before installing
-v, --verbose- 启用详细输出。
- 如果设置了https://cmake.org/cmake/help/v3.15/envvar/VERBOSE.html#envvar:VERBOSE环境变量，则可以省略此选项。
运行cmake–install，没有快速帮助选项。
打开项目
cmake --open
在关联的应用程序中打开生成的项目。只有某些生成器支持此功能
运行脚本
cmake [{-D =
以cmake语言编写的脚本的形式处理给定的cmake文件。不执行配置或生成步骤，缓存不会被修改。如果使用-D定义变量，则必须在-P参数之前完成。
运行命令行工具
CMake通过签名提供了内置的命令行工具
cmake -E
执行cmake -E或cmake -E help查看命令汇总。可用的命令是:
capabilities：以JSON格式报告cmake功能。输出是一个JSON对象，包含以下键:version：一个带有版本信息的JSON对象。键是:string：由cmake–version显示的完整版本字符串。major：整数形式的主版本号。minor：整数形式的次要版本号。patch：整数形式的补丁级别。suffix：cmake版本后缀字符串。isDirty：如果cmake生成来自 dirty tree，则设置bool。
generators：可用生成器列表。每个生成器都是一个带有以下键的JSON对象:name：包含生成器名称的字符串。toolsetSupport：如果生成器支持工具集，则为true，否则为false。platformSupport：如果生成器支持平台，则为true，否则为false。extraGenerators：包含与生成器兼容的所有额外生成器的字符串列表。
fileApi：当cmake-file-api(7)可用时出现的可选成员。该值是一个包含一个成员的JSON对象:requests：包含零个或多个受支持的文件api请求的JSON数组。每个请求都是一个JSON对象，其成员为：kind：指定支持的对象类型之一。version：一个JSON数组，其元素都是JSON对象，包含指定非负整数版本组件的主要和次要成员。
serverMode：如果cmake支持服务器模式，则为true，否则为false。
chdir[ ...] - 更改当前工作目录并运行命令。
compare_files [--ignore-eol]- 检查< file1>是否与< file2>相同。如果文件相同，则返回0，否则返回1。-ignore eol选项表示逐行比较并忽略LF/CRLF差异。
copy... - 将文件复制到< destination>（文件或目录）。
- 如果指定了多个文件，< destination>必须是目录并且必须存在。
- 不支持通配符。
- 复制遵循符号链接。这意味着它不复制符号链接，而是复制它指向的文件或目录。
copy_directory... - 将目录复制到< destination>目录。
- 如果< destination>目录不存在，将创建它。
- 复制目录遵循符号链接。
copy_if_different... - 如果文件已更改，请将其复制到< destination>（文件或目录）。
- 如果指定了多个文件，< destination>必须是目录并且必须存在。
- 遵循符号链接。
echo [...] - 将参数显示为文本。
echo_append [...] - 将参数显示为文本，但不显示新行。
env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...- 在修改后的环境中运行命令。
environment- 显示当前环境变量。
make_directory... - 创建< dir>目录。
- 如果需要，也可以创建父目录。
- 如果一个目录已经存在，它将被忽略
md5sum... - 为兼容md5sum格式的文件创建MD5校验和:
351abe79cd3800b38cdfb25d45015a15 file1.txt
052f86c15bbde68af55c7f7b340ab639 file2.txt
sha1sum... - 创建sha1sum兼容格式的文件校验和:
4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt
1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt
运行Find-Package工具
CMake为基于Makefile的项目提供类似pkg config的帮助程序：
cmake --find-package [<options>]
它使用find_package()搜索包，并将结果标记打印到stdout。它可以代替pkg-config在基于普通makefile的项目或基于autoconf的项目中找到已安装的库(通过share/aclocal/cmake.m4)。\
注意:由于某些技术限制，此模式不受很好的支持。保留它是为了兼容性，但不应该在新项目中使用。
查看帮助
要打印CMake文档中选定的页面，请使用
cmake --help[-<topic>]
使用以下选项之一：
--help,-help,-usage,-h,-H,/?
- 打印使用信息并退出。
- 用法描述基本命令行界面及其选项。
--version,-version,/V [
- 显示程序名称/版本标题并退出。
- 如果指定了一个文件，则将版本写入其中。如果给出帮助，将打印到指定的ile。
--help-full [
- 打印所有帮助手册并退出。
- 所有手册都以人类可读的文本格式打印。如果给出帮助< f >，将打印到指定的file。