cmake：命令行工具cmake

亦凉 2022-10-11 01:00 273阅读 0赞

# 概要 #

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 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配置选项。
     *  要维护原始的源代码树，请使用单独的专用生成树执行源代码外生成。也支持将生成树放置在与源树相同的目录中的源内生成，但不鼓励这样做。  
        ![在这里插入图片描述][20210629170530270.png]
 *  Generator
    
     *  这选择了要生成的构建系统的类型。
     *  请参阅cmake-generators(7)手册，了解所有生成器的文档。
     *  运行`cmake --help`查看本地可用的生成器列表。
     *  可以选择使用下面的`-G`选项来指定一个生成器，或者简单地接受当前平台的默认CMake选项。

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

# 生成项目构建系统 #

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

`cmake [<options>] <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

在所有情况下，可以是下面的0个或多个【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 listfiles之前从中加载缓存项的文件。加载的条目优先于项目的默认值。
 *  给定的文件应该是一个CMake脚本，其中包含使用CACHE选项的[set()][set]命令，而不是一个CACHE格式的文件。

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

*  创建或更新CMake缓存项。
 *  当CMake第一次在空生成树中运行时，它会创建一个CMakeCache.txt文件，并用项目的可自定义设置填充该文件。此选项可用于指定优先于项目默认值的设置。可以根据需要对任意多个缓存条目重复该选项。
 *  如果给定`:<type>`部分，则它必须是[set()][set]命令文档为其缓存签名指定的类型之一。
 *  如果省略了`:<type>`部分，那么如果条目不存在且已经存在类型，则将不使用类型创建条目。
 *  如果项目中的命令将类型设置为PATH或FILEPATH，则`<value>`将转换为绝对路径。
 *  此选项也可以作为单个参数提供：`-D<var>:<type>=<value>`或`-D<var>=<value>`。

`-U <globbing_expr>`

*  从CMake CACHE中删除匹配的条目。
 *  此选项可用于从CMakeCache.txt文件中删除一个或多个变量，使用\*和?都受支持。该选项可以对任意多个CACHE条目重复使用。
 *  小心使用，你可以使你的CMakeCache.txt不起作用。

`-G <generator-name>`

*  指定build system generator.
 *  CMake可能在某些平台上支持多个本机构建系统。生成器负责生成特定的构建系统。可能的生成器名称在cmake-generators(7)手册中指定。
 *  如果没有指定，CMake检查CMAKE\_GENERATOR环境变量，否则返回内置的默认选择。

`-T <toolset-spec>`

*  生成器的工具集规范（如果支持）。
 *  一些CMake生成器支持一个工具集规范来告诉本机构建系统如何选择编译器。详细信息请参见[CMAKE\_GENERATOR\_TOOLSET][CMAKE_GENERATOR_TOOLSET]变量。

`-A <platform-name>`

*  如果生成器支持，请指定平台名称。
 *  有些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项目的二叉树顶部运行，它将转储额外的信息，如缓存，日志文件等。

*  设置日志级别。
 *  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=<file>`

*  将cmake置于跟踪模式，但只输出指定文件的行。
 *  允许有多个选项。

`--warn-uninitialized`

*  对未初始化的值发出警告。
 *  当使用未初始化的变量时，打印警告。

`--warn-unused-vars`

*  警告未使用的变量。
 *  查找已声明或设置但未使用的变量。

`--no-warn-unused-cli`

*  不要对命令行选项发出警告。
 *  不要找到在命令行上声明但没有使用的变量。

`--check-system-vars`

*  查找系统文件中变量使用的问题。
 *  通常，只在CMAKE\_SOURCE\_DIR和CMAKE\_BINARY\_DIR中搜索未使用和未初始化的变量。这个标志也告诉CMake对其他文件发出警告。

# 构建项目 #

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

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

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

*  `--install <dir>`
    
     *  要安装的项目二进制目录。这是必须的，也必须是第一。
 *  `--config <cfg>`
    
     *  对于多配置生成器，选择配置`<cfg>`
 *  `--component <comp>`
    
     *  基于组件的安装。仅安装组件`<comp>` 。
 *  `--prefix <prefix>`
    
     *  覆盖安装前缀CMAKE\_INSTALL\_PREFIX。
 *  `--strip`
    
     *  Strip before installing
 *  `-v, --verbose`
    
     *  启用详细输出。
    
     *  如果设置了[https://cmake.org/cmake/help/v3.15/envvar/VERBOSE.html\#envvar:VERBOSE][https_cmake.org_cmake_help_v3.15_envvar_VERBOSE.html_envvar_VERBOSE]环境变量，则可以省略此选项。

运行cmake–install，没有快速帮助选项。

# 打开项目 #

`cmake --open <dir>`

在关联的应用程序中打开生成的项目。只有某些生成器支持此功能

# 运行脚本 #

`cmake [{-D <var>=<value>}...] -P <cmake-script-file>`

以cmake语言编写的脚本的形式处理给定的cmake文件。不执行配置或生成步骤，缓存不会被修改。如果使用-D定义变量，则必须在-P参数之前完成。

# 运行命令行工具 #

CMake通过签名提供了内置的命令行工具  
`cmake -E <command> [<options>]`

执行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`：指定支持的[对象类型][Link 1]之一。
             *  `version`：一个JSON数组，其元素都是JSON对象，包含指定非负整数版本组件的主要和次要成员。
     *  `serverMode`：如果cmake支持服务器模式，则为true，否则为false。
 *  `chdir <dir> <cmd> [<arg>...]`
    
     *  更改当前工作目录并运行命令。
 *  `compare_files [--ignore-eol] <file1> <file2>`
    
     *  检查< file1>是否与< file2>相同。如果文件相同，则返回0，否则返回1。-ignore eol选项表示逐行比较并忽略LF/CRLF差异。
 *  `copy <file>... <destination>`
    
     *  将文件复制到< destination>（文件或目录）。
     *  如果指定了多个文件，< destination>必须是目录并且必须存在。
     *  不支持通配符。
     *  复制遵循符号链接。这意味着它不复制符号链接，而是复制它指向的文件或目录。
 *  `copy_directory <dir>... <destination>`
    
     *  将目录复制到< destination>目录。
     *  如果< destination>目录不存在，将创建它。
     *  复制目录遵循符号链接。
 *  `copy_if_different <file>... <destination>`
    
     *  如果文件已更改，请将其复制到< destination>（文件或目录）。
     *  如果指定了多个文件，< destination>必须是目录并且必须存在。
     *  遵循符号链接。
 *  `echo [<string>...]`
    
     *  将参数显示为文本。
 *  `echo_append [<string>...]`
    
     *  将参数显示为文本，但不显示新行。
 *  `env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...`
    
     *  在修改后的环境中运行命令。
 *  `environment`
    
     *  显示当前环境变量。
 *  `make_directory <dir>...`
    
     *  创建< dir>目录。
     *  如果需要，也可以创建父目录。
     *  如果一个目录已经存在，它将被忽略
 *  `md5sum <file>...`
    
     *  为兼容md5sum格式的文件创建MD5校验和:

351abe79cd3800b38cdfb25d45015a15  file1.txt
    052f86c15bbde68af55c7f7b340ab639  file2.txt

*  `sha1sum <file>...`
    
     *  创建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 [<f>]`

*  显示程序名称/版本标题并退出。
 *  如果指定了一个文件，则将版本写入其中。如果给出帮助，将打印到指定的ile。

`--help-full [<f>]`

*  打印所有帮助手册并退出。
 *  所有手册都以人类可读的文本格式打印。如果给出帮助< f >，将打印到指定的file。

[CMake language]: https://cmake.org/cmake/help/v3.15/manual/cmake-language.7.html#manual:cmake-language%287%29
[20210629170530270.png]: /images/20221005/74e051c278b34c249cd4c30f19aa3ea2.png
[set]: https://cmake.org/cmake/help/v3.15/command/set.html#command:set
[CMAKE_GENERATOR_TOOLSET]: https://cmake.org/cmake/help/v3.15/variable/CMAKE_GENERATOR_TOOLSET.html#variable:CMAKE_GENERATOR_TOOLSET
[https_cmake.org_cmake_help_v3.15_envvar_VERBOSE.html_envvar_VERBOSE]: https://cmake.org/cmake/help/v3.15/envvar/VERBOSE.html#envvar:VERBOSE
[Link 1]: https://cmake.org/cmake/help/v3.15/manual/cmake-file-api.7.html#file-api-object-kinds