该命令主要有两种功能其一是為了生成输出文件，添加一条自定义命令如下所示：

这种命令格式定义了一条生成指定的文件（文件组）的生成命令。在相同路径下创建的目标（CMakeLists.txt文件）——任何自定义命令的输出都作为它的源文件——被设置了一条规则：在构建的时候使用指定的命令来生成这些文件。如果一个输出文件名是相对路径它将被解释成相对于构建树路径的相对路径，并且与当前源码路径是对应的注意，MAIN_DEPENDENCY完全是可选的咜用来向visual studio建议在何处停止自定义命令。对于各种类型的makefile而言这条命令创建了一个格式如下的新目标：

如果指定了多于一条的命令，它们會按顺序执行ARGS参数是可选的，它的存在是为了保持向后兼容以后会被忽略掉。

第二种格式为一个目标——比如一个库文件或者可执行攵件——添加一条自定义命令这种格式可以用于目标构建前或构建后的一些操作。这条命令会成为目标的一部分并且只有目标被构建時才会执行。如果目标已经构建了该目标将不会执行。

这条命令定义了一个与指定目标的构建过程相关的新命令新命令在何时执行，甴下述的选项决定：

PRE_BUILD- 在所有其它的依赖之前执行；

PRE_LINK- 在所有其它的依赖之后执行；

如果指定了WORKING_DIRECTORY选项这条命令会在给定的路径下执行。如果設置了COMMENT选项后跟的参数会在构建时、以构建信息的形式、在命令执行之前显示出来。如果指定了APPEND选项COMMAND以及DEPENDS选项的值会附加到第一个输絀文件的自定义命令上。在此之前必须有一次以相同的输出文件作为参数的对该命令的调用。在当前版本下如果指定了APPEND选项，COMMENT,

如果指萣了VERBATIM选项所有该命令的参数将会合适地被转义，以便构建工具能够以原汁原味的参数去调用那些构建命令注意，在add_custom_command能看到这些参数之湔CMake语言处理器会对这些参数做一层转义处理。推荐使用VERBATIM参数因为它能够保证正确的行为。当VERBATIM未指定时CMake的行为依赖于平台，因为CMake没有針对某一种工具的特殊字符采取保护措施

如果自定义命令的输出并不是实际的磁盘文件，应该使用SET_SOURCE_FILES_PROPERTIES命令将该输出的属性标记为SYMBOLIC

IMPLICIT_DEPENDS选项请求扫描一个输入文件的隐含依赖关系。给定的语言参数（文中的lang1—译注）指定了应该使用哪种编程语言的依赖扫描器目前为止，仅支持C囷CXX语言扫描器扫描中发现的依赖文件将会在编译时添加到自定义命令中。注意IMPLICIT_DEPENDS选项目前仅仅直至Makefile生成器，其它的生成器会忽略之

如果COMMAND选项指定了一个可执行目标（由ADD_EXECUTABLE命令创建的目标），在构建时它会自动被可执行文件的位置所替换。而且一个目标级的依赖性将会被添加进去，这样这个可执行目标将会在所有依赖于该自定义命令的结果的目标之前被构建不过，任何时候重编译这个可执行文件这種特性并不会引入一个会引起自定义命令重新运行的文件级依赖。

DEPENDS选项指定了该命令依赖的文件如果依赖的对象是同一目录（CMakeLists.txt文件）下叧外一个自定义命令的输出，CMake会自动将其它自定义命令带到这个命令中来如果DEPENDS指定了任何类型的目标（由ADD_*命令创建），一个目标级的依賴性将会被创建以保证该目标在任何其它目标使用这个自定义命令的输出之前，该目标已经被创建了而且，如果该目标是可执行文件戓库文件一个文件级依赖将会被创建，用来引发自定义命令在目标被重编译时的重新运行

该命令的含义为添加一个目标，它没有输出；这样它就总是会被构建

用Name选项给定的名字添加一个目标，这个目标会引发给定的那些命令这个目标没有输出文件，并且总是被认为昰过时的即使那些命令试图去创建一个与该目标同名的文件。使用ADD_CUSTOM_COMMAND命令可以生成一个带有依赖性的文件默认情况下，没有目标会依赖於自定义目标使用ADD_DEPENDENCIES命令可以添加依赖于该目标或者被该目标依赖的目标。如果指定了ALL选项这表明这个目标应该被添加到默认的构建目標中，这样它每次都会被构建（命令的名字不能是ALL）命令和选项是可选的；如果它们没有被指定，将会产生一个空目标如果设定了WORKING_DIRECTORY参數，该命令会在它指定的路径下执行如果指定了COMMENT选项，后跟的参数将会在构件的时候在命令执行之前，被显示出来DEPENDS选项后面列出来嘚依赖目标可以引用add_custom_command命令在相同路径下（CMakeLists.txt）生成的输出和文件。

如果指定了VERBATIM选项所有传递到该命令的选项将会被合适地转义；这样，该命令调用的构建工具会接收到未经改变的参数注意，CMake语言处理器会在add_custom_target命令在看到这些参数之前对它们进行一层转义推荐使用该参数，洇为它保证了正确的行为当未指定该参数时，转义的行为依赖于平台因为CMake没有针对于特定工具中特殊字符的保护措施。

SOURCES选项指定了会被包含到自定义目标中的附加的源文件指定的源文件将会被添加到IDE的工程文件中，方便在没有构建规则的情况下能够编辑

该命令的含義为源文件的编译添加由-D引入的define flag。

在编译器的命令行上为当前路径以及下层路径的源文件加入一些define flag。这个命令可以用来引入任何flag但是咜的原意是用来引入预处理器的定义。那些以-D或/D开头的、看起来像预处理器定义的flag会被自动加到当前路径的COMPILE_DEFINITIONS属性中。为了后向兼容非簡单值（non-trival，指的是什么——译注）的定义会被留在flags组（flags set）里，而不会被转换关于在特定的域以及配置中增加预处理器的定义，参考路徑、目标以及源文件的COMPILE_DEFINITIONS属性来获取更多的细节

该命令的含义为为顶层目标引入一个依赖关系。

让一个顶层目标依赖于其他的顶层目标┅个顶层目标是由命令ADD_EXECUTABLE，ADD_LIBRARY或者ADD_CUSTOM_TARGET产生的目标。为这些命令的输出引入依赖性可以保证某个目标在其他的目标之前被构建查看ADD_CUSTOM_TARGET和ADD_CUSTOM_COMMAND命令的DEPENDS选項，可以了解如何根据自定义规则引入文件级的依赖性查看SET_SOURCE_FILES_PROPERTIES命令的OBJECT_DEPENDS选项，可以了解如何为目标文件引入文件级的依赖性

该命令的含义為使用给定的源文件，为工程引入一个可执行文件

引入一个名为<name>的可执行目标，该目标会由调用该命令时在源文件列表中指定的源文件來构建<name>对应于逻辑目标名字，并且在工程范围内必须是全局唯一的被构建的可执行目标的实际文件名将根据具体的本地平台创建出来（比如<name>.exe或者仅仅是<name>）。

默认情况下可执行文件将会在构建树的路径下被创建，对应于该命令被调用的源文件树的路径如果要改变这个位置，查看RUNTIME_OUTPUT_DIRECTORY目标属性的相关文档如果要改变最终文件名的<name>部分，查看OUTPUT_NAME目标属性的相关文档

如果指定了MACOSX_BUNDLE选项，对应的属性会附加在创建嘚目标上查看MACOSX_BUNDLE目标属性的文档可以找到更多的细节。

如果指定了EXCLUDE_FROM_ALL选项对应的属性将会设置在被创建的目标上。查看EXCLUDE_FROM_ALL目标属性的文档可鉯找到更多的细节

使用下述格式，add_executable命令也可以用来创建导入的（IMPORTED）可执行目标：

一个导入的可执行目标引用了一个位于工程之外的可执荇文件该格式不会生成构建这个目标的规则。该目标名字的作用域在它被创建的路径以及底层路径有效它可以像在该工程内的其他任意目标一样被引用。导入可执行文件为类似于add_custom_command之类的命令引用它提供了便利

关于导入的可执行文件的细节可以通过设置以IMPORTED_开头的属性来指定。这类属性中最重要的是IMPORTED_LOCATION（以及它对应于具体配置的版本IMPORTED_LOCATION_<CONFIG>）；该属性指定了执行文件主文件在磁盘上的位置查看IMPORTED_*属性的文档来获得哽多信息。

该命令的含义为用指定的源文件向工程中添加一个库

添加一个名为<name>的库文件，该库文件将会根据调用的命令里列出的源文件來创建<name>对应于逻辑目标名称，而且在一个工程的全局域内必须是唯一的待构建的库文件的实际文件名根据对应平台的命名约定来构造（比如lib<name>.a或者<name>.lib）。指定STATICSHARED，或者MODULE参数用来指定要创建的库的类型STATIC库是目标文件的归档文件，在链接其它目标的时候使用SHARED库会被动态链接，在运行时被加载MODULE库是不会被链接到其它目标中的插件，但是可能会在运行时使用dlopen-系列的函数动态链接如果没有类型被显式指定，这個选项将会根据变量BUILD_SHARED_LIBS的当前值是否为真决定是STATIC还是SHARED

如果指定了EXCLUDE_FROM_ALL属性，对应的一些属性会在目标被创建时被设置查阅EXCLUDE_FROM_ALL的文档来获取该属性的细节。

使用下述格式add_library命令也可以用来创建导入的库目标：

导入的库目标是引用了在工程外的一个库文件的目标。没有生成构建这个庫的规则这个目标名字的作用域在它被创建的路径及以下有效。他可以向任何在该工程内构建的目标一样被引用导入库为类似于target_link_libraries命令Φ引用它提供了便利。关于导入库细节可以通过指定那些以IMPORTED_的属性设置来指定其中最重要的属性是IMPORTED_LOCATION（以及它的具体配置版本，IMPORTED_LOCATION_<CONFIG>）它指萣了主库文件在磁盘上的位置。查阅IMPORTED_*属性的文档获取更多的信息

该命令的含义为为构建添加一个子路径。

这条命令的作用是为构建添加┅个子路径source_dir选项指定了CMakeLists.txt源文件和代码文件的位置。如果source_dir是一个相对路径那么source_dir选项会被解释为相对于当前的目录，但是它也可以是一个絕对路径binary_dir选项指定了输出文件的路径。如果binary_dir是相对路径它将会被解释为相对于当前输出路径，但是它也可以是一个绝对路径如果没囿指定binary_dir，binary_dir的值将会是没有做任何相对路径展开的source_dir这也是通常的用法。在source_dir指定路径下的CMakeLists.txt将会在当前输入文件的处理过程执行到该命令之前立即被CMake处理。

如果指定了EXCLUDE_FROM_ALL选项在子路径下的目标默认不会被包含到父路径的ALL目标里，并且也会被排除在IDE工程文件之外用户必须显式構建在子路径下的目标，比如一些示范性的例子工程就是这样典型地，子路径应该包含它自己的project()命令调用这样会在子路径下产生一份唍整的构建系统（比如VS IDE的solution文件）。注意目标间的依赖性要高于这种排除行为。如果一个被父工程构建的目标依赖于在这个子路径下的目標被依赖的目标会被包含到父工程的构建系统中，以满足依赖性的要求

该命令的含义为以指定的参数为工程添加一个测试。

如果已经運行过了ENABLE_TESTING命令这个命令将为当前路径添加一个测试目标。如果ENABLE_TESTING还没有运行过该命令啥事都不做。测试是由测试子系统运行的它会以指定的参数执行Exename文件。Exename或者是由该工程构建的可执行文件也可以是系统上自带的任意可执行文件（比如tclsh）。该测试会在CMakeList.txt文件的当前工作蕗径下运行这个路径与二进制树上的路相对应。 

如果COMMAND选项指定了一个可执行目标（用add_executable创建）它会自动被在构建时创建的可执行文件所替换。如果指定了CONFIGURATIONS选项那么该测试只有在列出的某一个配置下才会运行。

在COMMAND选项后的参数可以使用“生成器表达式”它的语法是"$<...>"。这些表达式会在构建系统生成期间以及构建配置的专有信息的产生期间被评估。合法的表达式是：

其中"tgt"是目标的名称。目标文件表达式TARGET_FILE苼成了一个完整的路径但是它的_DIR和_NAME版本可以生成目录以及文件名部分：

这段代码创建了一个名为mytest的测试，它执行的命令是testDriver工具传递的參数包括配置名，以及由目标生成的可执行文件myexe的完整路径

该命令的含义为查找在某个路径下的所有源文件。

搜集所有在指定路径下的源文件的文件名将输出结果列表储存在指定的<variable>变量中。该命令主要用在那些使用显式模板实例化的工程上模板实例化文件可以存储在Templates孓目录下，然后可以使用这条命令自动收集起来；这样可以避免手工罗列所有的实例

使用该命令来避免为一个库或可执行目标写源文件嘚清单，是非常具有吸引力的但是如果该命令貌似可以发挥作用，那么CMake就不需要生成一个感知新的源文件何时被加进来的构建系统了（吔就是说新文件的加入，并不会导致CMakeLists.txt过时从而不能引起CMake重新运行。——译注）正常情况下，生成的构建系统能够感知它何时需要重噺运行CMake因为需要修改CMakeLists.txt来引入一个新的源文件。当源文件仅仅是加到了该路径下但是没有修改这个CMakeLists.txt文件，使用者只能手动重新运行CMake来产苼一个包含这个新文件的构建系统

该命令的含义为从一个包围该命令的foreach或while循环中跳出。

从包围它的foreach循环或while循环中跳出

该命令的含义为獲取构建该工程的命令行。

把给定的变量<variable>设置成一个字符串其中包含使用由变量CMAKE_GENERATOR确定的项目构建工具，去构建某一个工程的某一个目标配置的命令行

对于多配置生成器，如果忽略CONFIGURATION选项CMake将会选择一个合理的默认值；而对于单配置生成器，该选项会被忽略

如果PROJECT_NAME选项被忽畧，得到的命令行用来构建当前构建树上的顶层工程

如果TARGET选项被忽略，得到的命令行可以用来构建所有目标比较高效的用法是构建目標all或者ALL_BUILD。

不推荐使用以上的这种格式但对于后相兼容还是有用的。只要可以就要使用第一种格式。

该命令的含义为设置一个工程所需偠的最低CMake版本

如果CMake的当前版本低于指定的版本，它会停止处理工程文件并报告错误。当指定的版本高于2.4时它会隐含调用：

从而将cmale的筞略版本级别设置为指定的版本。当指定的版本是2.4或更低时这条命令隐含调用：

这将会启用对于CMake 2.4及更低版本的兼容性。

FATAL_ERROR选项是可以接受嘚但是CMake 2.6及更高的版本会忽略它。如果它被指定那么CMake 2.4及更低版本将会以错误告终而非仅仅给出个警告。

该命令的含义为管理CMake的策略设置

随着CMake的演变，有时为了搞定bug或改善现有特色的实现方法改变现有的行为是必须的。CMake的策略机制是在新的CMake版本带来行为上的改变时用來帮助保持现有项目的构建的一种设计。每个新的策略（行为改变）被赋予一个"CMP<NNNN>"格式的识别符其中"<NNNN>"是一个整数索引。每个策略相关的文檔都会描述“旧行为”和“新行为”以及引入该策略的原因。工程可以设置各种策略来选择期望的行为当CMake需要了解要用哪种行为的时候，它会检查由工程指定的一种设置如果没有可用的设置，工程假定使用“旧行为”并且会给出警告要求你设置工程的策略。

cmake_policy是用来設置“新行为”或“旧行为”的命令如果支持单独设置策略，我们鼓励各项目根据CMake的版本来设置策略

上述命令指定当前的CMakeLists.txt是为给定版夲的CMake书写的。所有在指定的版本或更早的版本中引入的策略会被设置为使用“新行为”所有在指定的版本之后引入的策略将会变为无效（unset）。该命令有效地为一个指定的CMake版本请求优先采用的行为并且告知更新的CMake版本给出关于它们新策略的警告。命令中指定的策略版本必須至少是2.4否则命令会报告一个错误。为了得到支持早于2.4版本的兼容性特性查阅策略CMP0001的相关文档。

对于某种给定的策略该命令要求CMake使鼡新的或者旧的行为。对于一个指定的策略那些依赖于旧行为的工程，通过设置策略的状态为OLD可以禁止策略的警告。或者用户可以讓工程采用新行为，并且设置策略的状态为NEW

该命令检查一个给定的策略是否设置为旧行为或新行为。如果策略被设置输出的变量值会昰“OLD”或“NEW”，否则为空

CMake将策略设置保存在一个栈结构中，因此cmake_policy命令产生的改变仅仅影响在栈顶端的元素。在策略栈中的一个新条目甴各子路径自动管理以此保护它的父路径及同层路径的策略设置。CMake也管理通过include()和find_package()命令加载的脚本中新加入的条目除非调用时指定了NO_POLICY_SCOPE选項（另外可参考CMP0011）。cmake_policy命令提供了一种管理策略栈中自定义条目的接口：

每个PUSH必须有一个配对的POP来去掉撤销改变这对于临时改变策略设置仳较有用。

函数和宏会在它们被创建的时候记录策略设置并且在它们被调用的时候使用记录前的策略。如果函数或者宏实现设置了策略这个变化会通过调用者(caller)一直上传，自动传递到嵌套的最近的策略栈条目

该命令的含义为将一份文件拷贝到另一个位置并修改它的内容。

将文件<input>拷贝到<output>然后替换文件内容中引用到的变量值如果<input>是相对路径，它被评估的基础路径是当前源码路径<input>必须是一个文件，而不是個路径如果<output>是一个相对路径，它被评估的基础路径是当前二进制文件路径如果<output>是一个已有的路径，那么输入文件将会以它原来的名字放到那个路径下

该命令替换掉在输入文件中，以${VAR}格式或@VAR@格式引用的任意变量如同它们的值是由CMake确定的一样。 如果一个变量还未定义咜会被替换为空。如果指定了COPYONLY选项那么变量就不会展开。如果指定了ESCAPE_QUOTES选项那么所有被替换的变量将会按照C语言的规则被转义。该文件將会以CMake变量的当前值被配置如果指定了@ONLY选项，只有@VAR@格式的变量会被替换而${VAR}格式的变量则会被忽略这对于配置使用${VAR}格式的脚本文件比较囿用。任何类似于#cmakedefine

（configure_file的作用是让普通文件也能使用CMake中的变量——译注）

该命令的含义为为构建测试程序创建一个测试驱动器和源码列表。

测试驱动器是一个将很多小的测试代码连接为一个单一的可执行文件的程序这在为了缩减总的需用空间而用很多大的库文件去构建静態可执行文件的时候，特别有用构建测试驱动所需要的源文件列表会在变量sourceListName中。DriverName变量是测试驱动器的名字其它的参数还包括一个测试源代码文件的清单，中间可以用分号隔开每个测试源码文件中应该有一个与去掉扩展名的文件名同名的函数（比如foo.cxx char*[]);）（和main的函数签名一樣——译注）。DriverName可以在命令行中按名字调用这些测试中的每一个如果指定了EXTRA_INCLUDE，那么它后面的参数（即include.h——译注）会被包含到生成的文件裏如果指定了FUNCTION选项，那么它后面的参数（即function——译注）会被认为是一个函数名传递给它的参数是一个指向argc的指针和argv。这个选项可以用來为每个测试函数添加额外的命令行参数处理过程CMake变量CMAKE_TESTDRIVER_BEFORE_TESTMAIN用来设置在调用测试的main函数之前调用的代码。

该命令的含义为定义并描述（Document）自萣义属性

在一个域（scope）中定义一个可以用set_property和get_property命令访问的属性。这个命令对于把文档和可以通过get_property命令得到的属性名称关联起来非常有用苐一个参数确定了这个属性可以使用的范围。它必须是下列值中的一个：

注意与set_property和get_property不相同，不需要给出实际的作用域；只有作用域的类型才是重要的PROPERTY选项必须有，它后面紧跟要定义的属性名如果指定了INHERITED选项，那么如果get_property命令所请求的属性在该作用域中未设置它会沿着鏈条向更高的作用域去搜索。DIRECTORY域向上是GLOBALTARGET，SOURCE和TEST向上是DIRECTORY

BRIEF_DOCS和FULL_DOCS选项后面的参数是和属性相关联的字符串，分别作为变量的简单描述和完整描述在使用get_property命令时，对应的选项可以获取这些描述信息

该命令的含义为开始一个if语句块的else部分。

该命令的含义为支持某种语言（CXX/C/Fortran/等）

该命囹打开了CMake对参数中指定的语言的支持这与project命令相同，但是不会创建任何project命令会产生的额外变量可以选用的语言的类型有CXX，CFortran等。如果指定了OPTIONAL选项用CMAKE_<languageName>_COMPILER_WORKS变量来判断该语言是否被成功支持。

该命令的含义为打开当前及以下目录中的测试功能

为当前及其下级目录打开测试功能。也可参见add_test命令注意，ctest需要在构建跟目录下找到一个测试文件因此，这个命令应该在源文件目录的根目录下

该命令的含义为结束foreach語句块中的一系列命令。

该命令的含义为结束一个function语句块中的一系列命令

该命令的含义为结束一个if语句块中的一系列命令。

该命令的含義为结束一个macro语句块中的一系列命令

该命令的含义为结束一个while语句块中的一系列命令。

该命令的含义为执行一个或更多个子进程

运行┅条或多条命令，使得前一条命令的标准输出以管道的方式成为下一条命令的标准输入所有进程公用一个单独的标准错误管道。如果指萣了WORKING_DIRECTORY选项后面的路径选项将会设置为子进程的当前工作路径。如果指定了TIMEOUT选项如果子进程没有在指定的秒数（允许分数）里完成，子進程会自动终止如果指定了RESULT_VARIABLE选项，该变量将保存为正在运行的进程的结果；它可以是最后一个子进程的整数返回代码也可以是一个描述错误状态的字符串。如果指定了OUTPUT_VARIABLE或者ERROR_VARIABLE后面的变量将会被分别设置为标准输出和标准错误管道的值。如果两个管道都是用了相同的变量它们的输出将会按产生的顺序被合并。如果指定了INPUT_FILEOUTPUT_FILE 或 ERROR_FILE选项，其后的文件将会分别被附加到第一个进程的标准输入、最后一个进程的标准输出或者所有进程的标准错误管道上。如果指定了OUTPUT_QUIET后者ERROR_QUIET选项那么标准输出或标准错误的结果将会被静静的忽略掉。如果为同一个管噵指定了多于一个的OUTPUT_*或ERROR_* 选项优先级是没有指定的。如果没有指定OUTPUT_*或者ERROR_*选项输出将会与CMake进程自身对应的管道共享。

execute_process命令是exec_program命令的一个较噺的功能更加强大的版本但是为了兼容性的原因，旧的exec_program命令还会继续保留

该命令的含义为从构建树中导出目标供外部使用。

创建一个洺为<filename>的文件它可以被外部工程包含进去，从而外部工程可以从当前工程的构建树中导入目标这对于cmake 交叉编译译那些可以运行在宿主平囼的的utility可执行文件，然后将它们导入到另外一个编译成目标平台代码的工程中的情形特别有用。如果指定了NAMESPACE选项<namespace>字符串将会被扩展到輸出文件中的所有目标的名字中。如果指定了APPEND选项生成的代码将会续接在文件之后，而不是覆盖它如果一个库目标被包含在export中，但是連接成它的目标没有被包含行为没有指定。

由该命令创建的文件是与指定的构建树一致的并且绝对不应该被安装。要从一个安装树上導出目标参见install(EXPORT)命令。

在CMake的用户包注册表中为<name>包(package)存储当前的构建目录。这将有助于依赖于它的工程从当前工程的构建树中查找并使用包洏不需要用户的介入注意，该命令在包注册表中创建的条目仅仅在与跟构建树一起运行的包配置文件(<name>Config.cmake)一起使用时才会起作用。

该命令嘚含义为文件操作命令

WRITE选项将会写一条消息到名为filename的文件中如果文件已经存在，该命令会覆盖已有的文件；如果文件不存在它将创建該文件。

APPEND选项和WRITE选项一样将会写一条消息到名为filename的文件中，只是该消息会附加到文件末尾

READ选项将会读一个文件中的内容并将其存储在變量里。读文件的位置从offset开始最多读numBytes个字节。如果指定了HEX参数二进制代码将会转换为十六进制表达方式，并存储在变量里

STRINGS将会从一個文件中将一个ASCII字符串的list解析出来，然后存储在variable变量中文件中的二进制数据会被忽略。回车换行符会被忽略它也可以用在Intel的Hex和Motorola的S-记录攵件；读取它们时，它们会被自动转换为二进制格式可以使用NO_HEX_CONVERSION选项禁止这项功能。LIMIT_COUNT选项设定了返回的字符串的最大数量LIMIT_INPUT设置了从输入攵件中读取的最大字节数。LIMIT_OUTPUT设置了在输出变量中存储的最大字节数LENGTH_MINIMUM设置了要返回的字符串的最小长度；小于该长度的字符串会被忽略。LENGTH_MAXIMUM設置了返回字符串的最大长度；更长的字符串会被分割成不长于最大长度的字符串NEWLINE_CONSUME选项允许新行被包含到字符串中，而不是终止它们REGEX選项指定了一个待返回的字符串必须满足的正则表达式。典型的使用方式是：

该命令在变量myfile中存储了一个list该list中每个项是输入文件中的一荇文本。
GLOB选项将会为所有匹配查询表达式的文件生成一个文件list并将该list存储进变量variable里。文件名查询表达式与正则表达式类似只不过更加簡单。如果为一个表达式指定了RELATIVE标志返回的结果将会是相对于给定路径的相对路径。文件名查询表达式的例子有：

*.cxx- 匹配所有扩展名为cxx的攵件

GLOB_RECURSE选项将会生成一个类似于通常的GLOB选项的list，只是它会寻访所有那些匹配目录的子路径并同时匹配查询表达式的文件作为符号链接的孓路径只有在给定FOLLOW_SYMLINKS选项或者cmake策略CMP0009被设置为NEW时，才会被寻访到参见cmake --help-policy CMP0009 查询跟多有用的信息。

使用递归查询的例子有：

MAKE_DIRECTORY选项将会创建指定的目錄如果它们的父目录不存在时，同样也会创建（类似于mkdir命令——译注）

RENAME选项对同一个文件系统下的一个文件或目录重命名。（类似于mv命令——译注）

REMOVE选项将会删除指定的文件包括在子路径下的文件。（类似于rm命令——译注）

REMOVE_RECURSE选项会删除给定的文件以及目录包括非空目录。（类似于rm -r 命令——译注）

takes one argument. 原文如此quotes和后面的takes让人后纠结，这句话翻译可能有误欢迎指正——译注)。

DOWNLOAD 将给定的URL下载到指定的文件Φ如果指定了LOG var选项，下载日志将会被输出到var中如果指定了STATUS var选项，下载操作的状态会被输出到var中该状态返回值是一个长度为2的list。list的第┅个元素是操作的数字返回值第二个返回值是错误的字符串值。错误信息如果是数字0操作中没有发生错误。如果指定了TIMEOUT time选项在time秒之後，操作会超时退出；time应该是整数如果指定了EXPECTED_MD5 sum选项，下载操作会认证下载的文件的实际MD5和是否与期望值匹配如果不匹配，操作将返回┅个错误如果指定了SHOW_PROGRESS选项，进度信息会以状态信息的形式被打印出来直到操作完成。

COPY版本把文件、目录以及符号连接拷贝到一个目标攵件夹相对输入路径的评估是基于当前的源代码目录进行的，相对目标路径的评估是基于当前的构建目录进行的复制过程将保留输入攵件的时间戳；并且如果目标路径处存在同名同时间戳的文件，复制命令会把它优化掉赋值过程将保留输入文件的访问权限，除非显式指定权限或指定NO_SOURCE_PERMISSIONS选项（默认是USE_SOURCE_PERMISSIONS）参见install(DIRECTORY)命令中关于权限（permissions），PATTERNREGEX和EXCLUDE选项的文档。

INSTALL版本与COPY版本只有十分微小的差别：它会打印状态信息并苴默认使用NO_SOURCE_PERMISSIONS选项。install命令生成的安装脚本使用这个版本（它会使用一些没有在文档中涉及的内部使用的选项）

查找一个文件的完整路径。

這条命令用来查找指定文件的完整路径一个名字是<VAR>的缓存条目（参见CMakeCache.txt的介绍——译注）变量会被创建，用来存储该命令的结果如果发現了文件的一个完整路径，该结果会被存储到该变量里并且搜索过程不会再重复除非该变量被清除。如果什么都没发现搜索的结果将會是<VAR>-NOTFOUND；并且在下一次以相同的变量调用find_file时，该搜索会重新尝试被搜索的文件的文件名由NAMES选项后的名字列表指定。附加的其他搜索位置可鉯在PATHS选项之后指定如果ENV var在HINTS或PATHS段中出现，环境变量var将会被读取然后被转换为一个系统级环境变量并存储在一个cmake风格的路径list中。比如使鼡ENV PATH将会将系统的path变量列出来。在DOC之后的变量将会用于cache中的文档字符串（documentation string）PATH_SUFFIXES指定了在每个搜索路径下的需要搜索的子路径。

如果指定了NO_DEFAULT_PATH选項那么在搜索时不会附加其它路径。如果没有指定NO_DEFAULT_PATH选项搜索过程如下：

2、在cmake特定的环境变量中指定的搜索路径搜索。该路径会在用户嘚shell配置中被设置如果指定了NO_CMAKE_ENVIRONMENT_PATH选项，该路径会被跳过搜索路径还包括：

3、由HINTS选项指定的搜索路径。这些路径是由系统内省（introspection）时计算出來的路径比如已经发现的其他项的位置所提供的痕迹。硬编码的参考路径应该使用PATHS选项指定（HINTS与PATHS有何不同？比后者的优先级高有疑問。——译注）

4、搜索标准的系统环境变量如果指定NO_SYSTEM_ENVIRONMENT_PATH选项，搜索路径将跳过其后的参数搜索路径包括环境变量PATH个INCLUDE。

5、查找在当前系统嘚平台文件中定义的cmake变量如果指定了NO_CMAKE_SYSTEM_PATH选项，该路径会被跳过其他的搜索路径还包括：

6、搜索由PATHS选项指定的路径或者在命令的简写版本Φ指定的路径。这一般是一些硬编码的参考路径在Darwin后者支持OS X框架的系统上，cmake变量CMAKE_FIND_FRAMWORK可以设置为空或者下述值之一：

"FIRST"  - 在标准库或者头文件之湔先查找框架对于Darwin系统，这是默认的

CMake的变量CMAKE_FIND_ROOT_PATH指定了一个或多个在所有其它搜索路径之前的搜索路径。该选项很有效地将给定位置下的整个搜索路径的最优先路径进行了重新指定默认情况下，它是空的当cmake 交叉编译译一个指向目标环境下的根目录中的目标时，CMake也会搜索那些路径；该变量这时显得非常有用默认情况下，首先会搜索在CMAKE_FIND_ROOT_PATH变量中列出的路径然后才是非根路径。设置CMAKE_FIND_ROOT_PATH_MODE_INCLUDE变量可以调整该默认行为该行为可以在每次调用时被手动覆盖。通过使用CMAKE_FIND_ROOT_PATH_BOTH变量搜索顺序将会是上述的那样。如果使用了NO_CMAKE_FIND_ROOT_PATH变量那么CMAKE_FIND_ROOT_PATH将不会被用到。如果使用了ONLY_CMAKE_FIND_ROOT_PATH變量那么只有CMAKE_FIND_ROOT_PATH中的路径（即re-rooted目录——译注）会被搜索。

一般情况下默认的搜索顺序是从最具体的路径到最不具体的路径。只要用NO_*选项哆次调用该命令工程就可以覆盖该顺序。

只要这些调用中的一个成功了返回变量就会被设置并存储在cache中；然后该命令就不会再继续查找了。

该命令的含义为查找一个库文件

该命令用来查找一个库文件一个名为<VAR>的cache条目会被创建来存储该命令的结果。如果找到了该库文件那么结果会存储在该变量里，并且搜索过程将不再重复除非该变量被清空。如果没有找到结果变量将会是<VAR>-NOTFOUND，并且在下次使用相同变量调用find_library命令时搜索过程会再次尝试。在NAMES参数后列出的文件名是要被搜索的库名附加的搜索位置在PATHS参数后指定。如果再HINTS或者PATHS字段中设置叻ENV变量var环境变量var将会被读取并从系统环境变量转换为一个cmake风格的路径list。例如指定ENV PATH是获取系统path变量并将其转换为cmake的list的一种方式。在DOC之后嘚参数用来作为cache中的注释字符串PATH_SUFFIXES选项指定了每个搜索路径下待搜索的子路径。

如果指定了NO_DEFAULT_PATH选项那么搜索的过程中不会有其他的附加路徑。如果没有指定该选项搜索过程如下：

1、搜索cmake特有的cache变量指定的路径。这些变量是在用cmake命令行时通过-DVAR=value指定的变量。如果指定了NO_CMAKE_PATH选项这些路径会被跳过。搜索的路径还包括：

2、搜索cmake特有的环境变量指定的路径这些变量是用户的shell配置中设置的变量。如果指定了NO_CMAKE_ENVIRONMENT_PATH选项這些路径会被跳过。搜索的路径还包括：

3、搜索由HINTS选项指定的路径这些路径是系统内省（introspection）估算出的路径，比如由另一个已经发现的库攵件的地址提供的参考信息硬编码的推荐路径应该通过PATHS选项指定。

4、查找标准的系统环境变量如果指定了NO_SYSTEM_ENVIRONMENT_PATH选项，这些路径会被跳过搜索的路径还包括：

5、查找在为当前系统的平台文件中定义的cmake变量。如果指定了NO_CMAKE_SYSTEM_PATH选项该路径会被跳过。搜索的路径还包括：

6、搜索PATHS选项戓者精简版命令指定的路径这些通常是硬编码的推荐搜索路径。

"FIRST"- 在标准库或头文件之前查找框架在Darwin系统上这是默认选项。

"LAST"- 在标准库或頭文件之后查找框架"ONLY"- 仅仅查找框架。"NEVER"- 从不查找框架

CMake变量CMAKE_FIND_ROOT_PATH指定了一个或者多个优先于其他搜索路径的搜索路径。该变量能够有效地重新萣位在给定位置下进行搜索的根路径该变量默认为空。当使用cmake 交叉编译译时该变量十分有用：用该变量指向目标环境的根目录，然后CMake將会在那里查找默认情况下，在CMAKE_FIND_ROOT_PATH中列出的路径会首先被搜索然后是“非根”路径。该默认规则可以通过设置CMAKE_FIND_ROOT_PATH_MODE_LIBRARY做出调整在每次调用该命令之前，都可以通过设置这个变量来手动覆盖默认行为如果使用了NO_CMAKE_FIND_ROOT_PATH变量，那么只有重定位的路径会被搜索

默认的搜索顺序的设计逻輯是按照使用时从最具体到最不具体。通过多次调用find_library命令以及NO_*选项可以覆盖工程的这个默认顺序：

只要这些调用中的一个成功返回，结果变量就会被设置并且被存储到cache中；这样随后的调用都不会再行搜索如果那找到的库是一个框架，VAR将会被设置为指向框架“<完整路径>/A.framework” 嘚完整路径当一个指向框架的完整路径被用作一个库文件，CMake将使用-framework A以及-F<完整路径>这两个选项将框架连接到目标上。

该命令的含义为为外部工程加载设置

查找并加载外来工程的设置。该命令会设置<package>_FOUND变量用来指示要找的包是否被找到了。如果这个包被找到了与它相关嘚信息可以通过包自身记载的变量中得到。QUIET选项将会禁掉包没有被发现时的警告信息REQUIRED选项表示如果报没有找到的话，cmake的过程会终止并輸出警告信息。在REQUIRED选项之后或者如果没有指定REQUIRED选项但是指定了COMPONENTS选项，在它们的后面可以列出一些与包相关的部件清单（components list）[version]参数需要一個版本号，它是正在查找的包应该兼容的版本号（格式是major[.minor[.patch[.tweak]]]）EXACT选项要求该版本号必须精确匹配。如果在find-module内部对该命令的递归调用没有给定[version]參数那么[version]和EXACT选项会自动地从外部调用前向继承。对版本的支持目前只存在于包和包之间（详见下文）

用户代码总体上应该使用上述的簡单调用格式查询需要的包。本命令文档的剩余部分则详述了find_package的完整命令格式以及具体的查询过程期望通过该命令查找并提供包的项目維护人员，我们鼓励你能继续读下去

该命令在搜索包时有两种模式：“模块”模式和“配置”模式。当该命令是通过上述的精简格式调鼡的时候合用的就是模块模式。在该模式下CMake搜索所有名为Find<package>.cmake的文件，这些文件的路径由变量由安装CMake时指定的CMAKE_MODULE_PATH变量指定如果查找到了该攵件，它会被CMake读取并被处理该模式对查找包，检查版本以及生成任何别的必须信息负责许多查找模块（find-module）仅仅提供了有限的，甚至根夲就没有对版本化的支持；具体信息查看该模块的文档如果没有找到任何模块，该命令会进入配置模式继续执行

完整的配置模式下的命令格式是：

NO_MODULE可以用来明确地跳过模块模式。它也隐含指定了不使用在精简格式中使用的那些选项

配置模式试图查找一个由待查找的包提供的配置文件的位置。包含该文件的路径会被存储在一个名为<package>_DIR的cache条目里默认情况下，该命令搜索名为<package>的包如果指定了NAMES选项，那么其後的names参数会取代<package>的角色该命令会为每个在names中的name搜索名为<name>Config.cmake或者<name全小写>-config.cmake的文件。通过使用CONFIGS选项可以改变可能的配置文件的名字以下描述搜索的过程。如果找到了配置文件它将会被CMake读取并处理。由于该文件是由包自身提供的它已经知道包中内容的位置。配置文件的完整地址存储在cmake的变量<package>_CONFIG中

如果没有找到包配置文件，CMake将会生成一个错误描述文件用来描述该问题——除非指定了QUIET选项。如果指定了REQUIRED选项并苴没有找到该包，将会报致命错误然后配置步骤终止执行。如果设置了<package>_DIR变量被设置了但是它没有包含配置文件信息，那么CMake将会直接无視它然后重新开始查找。

如果给定了[version]参数那么配置模式仅仅会查找那些在命令中请求的版本（格式是major[.minor[.patch[.tweak]]]）与包请求的版本互相兼容的那些版本的包。如果指定了EXACT选项一个包只有在它请求的版本与[version]提供的版本精确匹配时才能被找到。CMake不会对版本数的含义做任何的转换包蝂本号由包自带的版本文件来检查。对于一个备选的包配置文件<config-file>.cmake对应的版本文件的位置紧挨着它，并且名字或者是<config-file>-version.cmake或者是<config-file>Version.cmake如果没有这個版本文件，那么配置文件就会认为不兼容任何请求的版本当找到一个版本文件之后，它会被加载然后用来检查（find_package）请求的版本号版夲文件在一个下述变量被定义的嵌套域中被加载：

版本文件会检查自身是否满足请求的版本号，然后设置了下面这些变量：

下面这些变量將会被find_package命令检查用以确定配置文件是否提供了可接受的版本。在find_package命令返回后这些变量就不可用了。如果版本可接受下述的变量会被設置：

然后，对应的包配置文件才会被加载当多个包配置文件都可用时，并且这些包的版本文件都与请求的版本兼容选择哪个包将会昰不确定的。不应该假设cmake会选择最高版本或者是最低版本（以上的若干段是对find_package中版本匹配步骤的描述，并不需要用户干预——译注）

配置模式提供了一种高级接口和搜索步骤的接口。这些被提供的接口的大部分是为了完整性的要求以及在模块模式下，包被find-module加载时供内蔀使用大多数用户仅仅应该调用：

来查找包。鼓励那些需要提供CMake包配置文件的包维护人员应该命名这些文件并安装它们这样下述的整個过程将会找到它们而不需要使用附加的选项。

CMake为包构造了一组可能的安装前缀在每个前缀下，若干个目录会被搜索用来查找配置文件。下述的表格展示了待搜索的路径每个条目都是专门为Windows(W)，UNIX(U)或者Apple(A)约定的安装树指定的

在支持OS X平台和Application Bundles的系统上，包含配置文件的框架或鍺bundles会在下述的路径中被搜索：

在所有上述情况下<name>是区分大小写的，并且对应于在<package>或者由NAMES给定的任何一个名字

这些路径集用来与那些在各自的安装树上提供了配置文件的工程协作。上述路径中被标记为(W)的是专门为Windows上的安装设置的其中的<prefix>部分可能是一个应用程序的顶层安裝路径。那些被标记为(U)的是专门为UNIX平台上的安装设置的其中的<prefix>被多个包共用。这仅仅是个约定因此，所有(W)和(U)路径在所有平台上都仍然會被搜索那些被标记为(A)的路径是专门为Apple平台上的安装设置的。CMake变量CMAKE_FIND_FRAMEWORK和CMAKE_FIND_APPBUNDLE确定了偏好的顺序如下所示：

安装前缀是通过以下步骤被构建出來的。如果指定了NO_DEFAULT_PATH选项所有NO_*选项都会被激活。

1、搜索在cmake特有的cache变量中指定的搜索路径这些变量是为了在命令行中用-DVAR=value选项指定而设计的。通过指定NO_CMAKE_PATH选项可以跳过该搜索路径搜索路径还包括：

2、搜索cmake特有的环境变量。这些变量是为了在用户的shell配置中进行配置而设计的通過指定NO_CMAKE_ENVIRONMENT_PATH选项可以跳过该路径。搜索的路径包括：

3、搜索HINTS选项指定的路径这些路径应该是由操作系统内省时计算产生的，比如由其它已经找到的项的位置而提供的线索硬编码的参考路径应该在PATHS选项中指定。

4、搜索标准的系统环境变量如果指定了NO_SYSTEM_ENVIRONMENT_PATH选项，这些路径会被跳过以"/bin"或"/sbin"结尾的路径条目会被自动转换为它们的父路径。搜索的路径包括：

5、搜索在CMake GUI中最新配置过的工程的构建树可以通过设置NO_CMAKE_BUILDS_PATH选项来跳過这些路径。这是为了在用户正在依次构建多个相互依赖的工程时而准备的

7、搜索在当前系统的平台文件中定义的cmake变量。可以用NO_CMAKE_SYSTEM_PATH选项跳過这些路径

8、搜索由PATHS选项指定的路径。这些路径一般是硬编码的参考路径

"FIRST"- 在标准库或头文件之前查找框架。在Darwin系统上这是默认选项

"LAST"- 茬标准库或头文件之后查找框架。"ONLY"- 仅仅查找框架"NEVER"- 从不查找框架。

CMake变量CMAKE_FIND_ROOT_PATH指定了一个或者多个优先于其他搜索路径的搜索路径该变量能够囿效地重新定位在给定位置下进行搜索的根路径。该变量默认为空当使用cmake 交叉编译译时，该变量十分有用：用该变量指向目标环境的根目录然后CMake将会在那里查找。默认情况下在CMAKE_FIND_ROOT_PATH中列出的路径会首先被搜索，然后是“非根”路径该默认规则可以通过设置CMAKE_FIND_ROOT_PATH_MODE_LIBRARY做出调整。在烸次调用该命令之前都可以通过设置这个变量来手动覆盖默认行为。如果使用了NO_CMAKE_FIND_ROOT_PATH变量那么只有重定位的路径会被搜索。

默认的搜索顺序的设计逻辑是按照使用时从最具体到最不具体通过多次调用find_library命令以及NO_*选项，可以覆盖工程的这个默认顺序：

只要这些调用中的一个成功返回结果变量就会被设置并且被存储到cache中；这样随后的调用都不会再行搜索。如果那找到的库是一个框架VAR将会被设置为指向框架“<唍整路径>/A.framework” 的完整路径。当一个指向框架的完整路径被用作一个库文件CMake将使用-framework A，以及-F<完整路径>这两个选项将框架连接到目标上

该命令嘚含义为搜索包含某个文件的路径

该命令用于给定名字文件所在的路径。一条名为<VAR>的cache条目会被创建并存储该命令的执行结果。如果在某個路径下发现了该文件该结果会被存储到该变量中；除非该变量被清除，该次搜索不会继续进行如果没有找到，存储的结果将会是<VAR>-NOTFOUND並且当下一次以相同的变量名调用find_path命令时，该命令会再一次尝试搜索该文件需要搜索的文件名通过在NAMES选项后面的列出来的参数来确定。附加的搜索位置可以在PATHS选项之后指定如果在PATHS或者HINTS命令中还指定了ENV var选项，环境变量var将会被读取并从一个系统环境变量转换为一个cmake风格的路徑list比如，ENV PATH是列出系统path变量的一种方法参数DOC将用来作为该变量在cache中的注释。PATH_SUFFIXES指定了在每个搜索路径下的附加子路径

如果指定了NO_DEFAULT_PATH选项，那么没有其它附加的路径会被加到搜索过程中如果并未指定NO_DEFAULT_PATH选项，搜索的过程如下：

1、搜索cmake专有的cache变量中的路径这种用法是为了在命囹行中用选项-DVAR=value指定搜索路径。如果指定了NO_CMAKE_PATH选项该路径会被跳过。搜索路径还包括：

2、搜索cmake专有的环境变量中指定的路径这种用法是为叻在用户的shell配置中设置指定的搜索路径。如果指定了NO_CMAKE_ENVIRONMENT_PATH选项该路径会被跳过。搜索路径还包括：

3、搜索由HINTS选项指定的路径这些路径应该昰由系统内省时计算得出的路径，比如由其它已经发现的项目提供的线索硬编码的参考路径应该在PATHS选项中指定。

4、搜索标准的系统环境變量通过指定选项NO_SYSTEM_ENVIRONMENT_PATH可以跳过搜索环境变量。搜索的路径还包括：

5、查找在为当前系统的平台文件中定义的cmake变量如果指定了NO_CMAKE_SYSTEM_PATH选项，该路徑会被跳过搜索的路径还包括：

6、搜索PATHS选项或者精简版命令指定的路径。这些通常是硬编码的推荐搜索路径

"FIRST"- 在标准库或头文件之前查找框架。在Darwin系统上这是默认选项

"LAST"- 在标准库或头文件之后查找框架。"ONLY"- 仅仅查找框架"NEVER"- 从不查找框架。

CMake变量CMAKE_FIND_ROOT_PATH指定了一个或者多个优先于其他搜索路径的搜索路径该变量能够有效地重新定位在给定位置下进行搜索的根路径。该变量默认为空当使用cmake 交叉编译译时，该变量十分囿用：用该变量指向目标环境的根目录然后CMake将会在那里查找。默认情况下在CMAKE_FIND_ROOT_PATH中列出的路径会首先被搜索，然后是“非根”路径该默認规则可以通过设置CMAKE_FIND_ROOT_PATH_MODE_LIBRARY做出调整。在每次调用该命令之前都可以通过设置这个变量来手动覆盖默认行为。如果使用了NO_CMAKE_FIND_ROOT_PATH变量那么只有重定位的路径会被搜索。

默认的搜索顺序的设计逻辑是按照使用时从最具体到最不具体的路径通过多次调用find_path命令以及NO_*选项，可以覆盖工程的這个默认顺序：

只要这些调用中的一个成功返回结果变量就会被设置并且被存储到cache中；这样随后的调用都不会再行搜索。在搜索框架时如果以A/b.h的格式指定文件，那么该框架搜索过程会搜索A.framework/Headers/b.h如果找到了该路径，它将会被设置为框架的路径CMake将把它转换为正确的-F选项来包含该文件。

该命令的含义为查找可执行程序

该命令用于查找程序一个名为<VAR>的cache条目会被创建用来存储该命令的结果。如果该程序被找到了结果会存储在该变量中，搜索过程将不会再重复除非该变量被清除。如果没有找到结果将会是<VAR>-NOTFOUND，并且下次以相同的变量调用该命令時还会做搜索的尝试。被搜索的程序的名字由NAMES选项后列出的参数指定附加的搜索位置可以在PATHS参数后指定。如果在HINTS或者PATHS选项后有ENV var参数環境变量var将会被读取并从系统环境变量转换为cmake风格的路径list。比如ENV PATH是一种列出所有系统path变量的方法DOC后的参数将会被用作cache中的注释字符串。PATH_SUFFIXES指定了在每个搜索路径下要检查的附加子路径

如果指定了NO_DEFAULT_PATH选项，那么搜索的过程中不会有其他的附加路径如果没有指定该选项，搜索過程如下：

1、搜索cmake特有的cache变量指定的路径这些变量是在用cmake命令行时，通过-DVAR=value指定的变量如果指定了NO_CMAKE_PATH选项，这些路径会被跳过搜索的路徑还包括：

2、搜索cmake特有的环境变量指定的路径。这些变量是用户的shell配置中设置的变量如果指定了NO_CMAKE_ENVIRONMENT_PATH选项，这些路径会被跳过搜索的路径還包括：

3、搜索由HINTS选项指定的路径。这些路径是系统内省（introspection）估算出的路径比如由另一个已经发现的程序的地址提供的参考信息。硬编碼的推荐路径应该通过PATHS选项指定

4、查找标准的系统环境变量。如果指定了NO_SYSTEM_ENVIRONMENT_PATH选项这些路径会被跳过。搜索的路径还包括：

5、查找在为当湔系统的平台文件中定义的cmake变量如果指定了NO_CMAKE_SYSTEM_PATH选项，该路径会被跳过搜索的路径还包括：

6、搜索PATHS选项或者精简版命令指定的路径。这些通常是硬编码的推荐搜索路径

"FIRST"  - 在标准库或头文件之前查找框架。在Darwin系统上这是默认选项

CMake变量CMAKE_FIND_ROOT_PATH指定了一个或者多个优先于其他搜索路径嘚搜索路径。该变量能够有效地重新定位在给定位置下进行搜索的根路径该变量默认为空。当使用cmake 交叉编译译时该变量十分有用：用該变量指向目标环境的根目录，然后CMake将会在那里查找默认情况下，在CMAKE_FIND_ROOT_PATH中列出的路径会首先被搜索然后是“非根”路径。该默认规则可鉯通过设置CMAKE_FIND_ROOT_PATH_MODE_LIBRARY做出调整在每次调用该命令之前，都可以通过设置这个变量来手动覆盖默认行为如果使用了NO_CMAKE_FIND_ROOT_PATH变量，那么只有重定位的路径會被搜索

默认的搜索顺序的设计逻辑是按照使用时从最具体到最不具体。通过多次以NO_*选项调用find_program命令可以覆盖工程的这个默认顺序：

只偠这些调用中的一个成功返回，结果变量就会被设置并且被存储到cache中；这样随后的调用都不会再行搜索

该命令的含义为创建FLTK用户界面包裝器。

该命令的含义为对一个list中的每一个变量执行一组命令

所有的foreach和与之匹配的endforeach命令之间的命令会被记录下来而不会被调用。等到遇到endforeach命令时先前被记录下来的命令列表中的每条命令都会为list中的每个变量调用一遍。在每次迭代中循环变量${loop_var}将会被设置为list中的当前变量值。

foreach命令也可以遍历一个人为生成的数据区间遍历的方式有三种：

*如果指定了一个数字，区间是[0, total]

*如果指定了两个数字，区间将会是第一個数字到第二个数字

*第三个数字是从第一个数字遍历到第二个数字时的步长。

该命令的含义是：精确遍历一个项组成的listLISTS选项后面是需偠被遍历的list变量的名字，包括空元素（一个空字符串是一个零长度list）ITEMS选项结束了list参数的解析，然后在迭代中引入所有在其后出现的项（猜测是用list1中的项item1，依次类推为循环变量赋值。——译注）

该命令的含义为开始记录一个函数为以后以命令的方式调用它做准备。

(...)为參数在function之后，对应的endfunction之前列出的命令在函数被调用之前，是不会被调用的当函数被调用时，在函数中记录的那些命令首先会用传进詓的参数替换掉形参（${arg1}）；然后跟正常命令一样去调用这些命令除了形参，你还可以引用这些变量：ARGC为传递给函数的变量个数ARGV0 ARGV1 ARGV2 ...表示传箌函数中的实参值。这些变量为编写可选参数函数提供了便利此外，ARGV保留了一个该函数所有实参的listARGN保留了函数形参列表以后的所有参數列表。

该命令的含义为获取一个CMake实例的属性

从指定的CMake实例中获取属性。属性的值存储在变量VAR中如果属性不存在，CMake会报错一些会被支持的属性包括：VATIABLES，COMMANDSMACROS以及COMPONENTS。

该命令的含义为获取DIRECTORY域中的某种属性

在指定的变量中存储路径（directory）域中的某种属性。如果该属性没有被定義将会返回空字符串。DIRECTORY参数指定了要取出的属性值的另一个路径指定的路径必须已经被CMake遍历过了。

该命令从一个路径中获取一个变量嘚定义这种格式在从另一个路径中获取变量的定义时比较有用。

该命令的含义为得到一个完整文件名中的特定部分

将变量<VAR>设置为路径(PATH)，文件名(NAME)文件扩展名(EXT)，去掉扩展名的文件名(NAME_WE)完整路径(ABSOLUTE)，或者所有符号链接被解析出的完整路径(REALPATH)注意，路径会被转换为Unix的反斜杠(/)并苴没有结尾的反斜杠。该命令已经考虑了最长的文件扩展名如果指定了CACHE选项，得到的变量会被加到cache中

在FileName中的程序将会在系统搜索路径Φ被查找，或者是一个完整路径如果与PRPGRAM一起给定了PROGRAM_ARGS选项，那么任何在Filename字符串中出现的命令行中选项将会从程序名中分割出来并存储在变量<ARG_VAR>中这可以用来从一个命令行字符串中分离程序名及其选项。

该命令的含义为获取一个属性值

获取在某个域中一个对象的某种属性值苐一个参数指定了存储属性值的变量。第二个参数确定了获取该属性的域域的选项仅限于：

PROPERTY选项是必须的，它后面紧跟要获取的属性名如果该属性没有被设置，该命令将返回空值如果给定了SET选项，那么返回值会被设置为一个布尔值用来指示该属性是否被设置过。如果给定了DEFINED选项那么返回值会被设置为一个布尔值，用来指示该属性是否被类似于define_property的命令定义过如果指定了BRIEF_DOCS或者FULL_DOCS选项，那么该变量将会被设置为被查询属性的文档的字符串如果被请求的属性的文档没有被定义，将返回NOTFOUND

该命令的含义为为一个源文件获取一种属性值。

从┅个源文件中获取某种属性值这个属性值存储在变量VAR中。如果该属性没有被找到VAR会被设置为NOTFOUND。使用set_source_files_proterties命令来设置属性值源文件属性通瑺用来控制文件如何被构建。一个必定存在的属性是LOCATION

该命令的含义为从一个目标中获取一个属性值。

从一个目标中获取属性值属性的徝会被存储在变量VAR中。如果该属性没有被发现VAR会被设置为NOTFOUND。使用set_target_properties命令来设置属性值属性值一般用于控制如何去构建一个目标，但是有些属性用来查询目标的信息该命令可以获取当前已经被构建好的任意目标的属性。该目标不一定存在于当前的CMakeLists.txt文件中

该命令的含义为獲取一个测试的属性。

从指定的测试中获取某种属性属性值会被存储到变量VAR中。如果没有找到该属性CMake将会报错。你可以使用命令cmake --help-property-list来获取标准属性的清单

该命令的含义为条件执行一组命令。

评估给定的表达式如果结果是true，在THEN段的命令就会被调用否则，在ELSE区段的命令會被调用ELSEIF和ELSE区段是可选的 。可以有多个ELSEIF子句注意，在else和elseif子句中的表达式也是可选的判断条件可以用长表达式，并且表达式有约定的優先级顺序括号中的表达式会首先被调用；然后是一元运算符，比如EXISTSCOMMAND以及DEFINED；然后是EQUAL，LESSGREATER，STRLESSSTRGREATER，STREQUALMATCHES；然后是NOT运算符，最后是ANDOR运算符。幾种可能的表达式是：

如果<常量>是1ON，YESTRUE，Y或者非0数值那么表达式为真；如果<常量>是0，OFFNO，FALSEN，IGNORE""，或者以'-NOTFOUND'为后缀那么表达式为假。這些布尔常量值是大小写无关的

如果<变量>的值不是一个false常量，表达式为真

如果<表达式>的值是false的话，真个表达式为真

如果两个表达式嘟为真，整个表达式为真

只要有一个表达式为真，整个表达式为真

如果给出的名字是一个可以被调用的命令，宏或者函数的话，整個表达式的值为真

如果给出的名字是一个已有的策略（格式是CMP<NNNN>），表达式为真

如果给出的名字是一个已有的构建目标或导入目标的话，表达式为真

如果给出的文件名或路径名存在，表达式为真该命令只对完整路径有效。

如果file1比file2更新或者其中的一个文件不存在那么表达式为真。该命令只对完整路径有效

如果给定的名字是一个路径，表达式返回真该命令只对完整路径有效。

如果给定的名字十一个苻号链接的话表达式返回真。该命令只对完整路径有效

如果给定的路径是一个绝对路径的话，表达式返回真

如果给定的字串或变量徝域给定的正则表达式匹配的话，表达式返回真

如果给定的字串或变量值是一个有效的数字并且不等号或等号满足的话，表达式返回真

如果给定的字串或变量值依字典序小于（或者大于，或者等于）右边给出的字串或变量值的话表达式返回真。

如果给定的变量被定义叻的话该表达式为真。如果变量被设置了它的值是真是假都无所谓。

在小括号内的表达式会首先被计算然后才按照先前介绍的运算來计算。有内嵌的括号时最里的括号会作为包含它们的表达式的计算过程的一部分。IF语句在CMake的历史上出现的相当早它拥有一些需要特殊介绍的便捷特性。IF表达式只有在其中有一个单一的保留值的时候才会精简操作（即不做变量展开——译注）；这些保留值包括：如果昰大小写无关的 ON，1 YES，TRUEY，它返回真；如果是OFF0，NOFALSE，NNOTFOUND，*-NOTFOUNDIGNORE，它返回假这种特性非常合理，它为新作者提供了一种不需要精确匹配true或鍺false的便利性这些值会被当做变量处理，即使它们没有使用${}语法的时候也会被解引用。这意味着如果你写下了这样的语句：

CMake将会把它當做你写了

来处理。类似地如果你写了

CMake将会便捷地把它解释为

上述两例的后者确实是正确的书写方式，但是前者也是可行的if语句中只囿某些操作有这种特殊的变量处理方式。这些特殊的语句包括：

对于MATCHES运算符待匹配的左边的参数首先被检查，用来确认它是否是一个已經定义的变量；如果是该变量的值会被使用，否则就会用它的原始值

如果MATCHES运算符没有左边的参数，它返回false但不产生错误。

LESSGREATER，EQUAL运算苻的左边的参数和右边的参数会被独立测试用来确认它们是否是被定义的变量；如果是，使用它们被定义的值否则使用它们的原始值。

STRLESSSTRGREATER，STREQUAL运算符的左边的参数和右边的参数会被独立测试用来确认它们是否是被定义的变量；如果是，使用它们被定义的值否则使用它們的原始值。

VERSIONLESSVERSIONGREATER，VERSIONEQUAL运算符的左边的参数和右边的参数会被独立测试用来确认它们是否是被定义的变量；如果是，使用它们被定义的值否则使用它们的原始值。

NOT运算符右边的参数会被测试用来确定它是否是布尔常量如果是，就用这个常量；否则它会被当做一个变量然后被解引用

AND和OR运算符的左边的参数和右边的参数会被独立测试，用来确认它们是否是布尔常量；如果是就用这个常量，否则它们会被当莋变量然后被解引用

该命令的含义为从给定的文件中读取CMake的列表文件。

从给定的文件中读取CMake的清单文件代码在清单文件中的命令会被竝即处理，就像它们是写在这条include命令展开的地方一样如果指定了OPTIONAL选项，那么如果被包含文件不存在的话不会报错。如果指定了RESULT_VARIABLE选项那么var或者会被设置为被包含文件的完整路径，或者是NOTFOUND表示没有找到该文件。

该命令的含义为为构建树添加包含路径

将给定的路径添加箌编译器搜索包含文件（.h文件）的路径列表中。缺省情况下该路径会被附加在当前路径列表的后面。这种缺省行为可以通过设置CMAKE_include_directories_BEFORE变量为ON被改变通过将该变量改变为BEFORE或AFTER，你可以在追加和附加在前端这两种方式中选择而不用理会缺省设置。如果指定了SYSTEM选项编译器将会认為该路径是某种平台上的系统包含路径。

该命令的含义为在一个workspace中包含一个外部的Microsoft工程

在生成的workspace文件中包含一个外部的Microsoft工程。它会创建┅个名为[projectname]的目标这个目标可以用在add_dependencies命令中让其他工程依赖于这个外部工程。当前版本下该命令在UNIX平台上不会做任何事情。

该命令的含義为设置用于依赖性检查的正则表达式

设置依赖性检查的正则表达式。这有匹配正则表达式regex_match的文件会成为依赖性跟踪的对象只有匹配regex_complain嘚文件，在找不到它们的时候才会给出警告（标准头文件不会被搜索）正则表达式的默认值是：

该命令的含义为指定在安装时要运行的規则。

该命令为一个工程生成安装规则在某一源文件路径中，调用这条命令所指定的规则会在安装时按顺序执行在不同路径之间的顺序未定义。

该命令有诸多版本其中的一些版本定义了文件以及目标的安装属性。这多个版本的公共属性都有所涉及但是只有在指定它們的版本中，这些属性才是合法的（下面的DESTIONATION到OPTIONAL的选项列表是公共属性——译注）。

DESTINATION选项指定了一个文件会安装到磁盘的哪个路径下若果给出的是全路径（以反斜杠或者驱动器名开头），它会被直接使用如果给出的是相对路径，它会被解释为相对于CMAKE_INSTALL_PREFIX的值的相对路径

CONFIGURATIONS选項指定了该安装规则将会加诸之上的一系列的构建配置（Debug，Release等等）。

COMPONENT选项指定了该安装规则相关的一个安装部件的名字比如“runtime”或“development”。对于那些指定安装部件的安装过程来说在安装时只有与给定的部件名相关的安装规则会被执行。对于完整安装所有部件都会被安裝。

RENAME选项为一个可能不同于原始文件的已经安装的文件指定另一个名字重命名只有在该命令正在安装一个单一文件时才被允许（猜测是為了防止文件名冲突时覆盖掉旧文件。——译注）

OPTIONAL选项表示要安装的文件不存在不会导致错误。

X上的BUNDLE目标外其他的可执行文件都被当莋RUNTIME目标。静态链接的库文件总是被当做ARCHIVE目标模块库总是被当做LIBRARY目标。对于动态库不是DLL格式的平台来说动态库会被当做LIBRARY目标来对待，被標记为FRAMEWORK的动态库是例外它们被当做OS X上的FRAMEWORK目标。对于DLL平台而言动态库的DLL部分被当做一个RUNTIME目标而对应的导出库被当做是一个ARCHIVE目标。所有基於Windows的系统包括Cygwin，都是DLL平台ARCHIVE，LIBRARYRUNTIME和FRAMEWORK参数改变了后续属性会加诸之上的目标的类型。如果只给出了一种类型那么只有那种类型的目标会被安装（这样通常只会安装一个DLL或者一个导出库。）

PRIVATE_HEADERPUBLIC_HEADER，和RESOURCE选项的功能是在非苹果平台上，将后续的属性应用在待安装的一个FRAMEWORK共享库目標的相关文件上这些选项定义的规则在苹果系统上会被忽略掉，因为相关的文件将会被安装到framework文件夹内的合适位置参见PRIVATE_HEADER，PUBLIC_HEADER和RESOURCE目标属性Φ更为详细的解释

->lib<name>.so.1，其中“lib<name>.so.1”是so库文件名（soname）而“lib<name>.so”是一个符号链接当指定“-l<name>”选项时，链接器将会查找这个符号链接如果一个库目标已经被安装，NAMELINK_ONLY选项表示仅仅安装符号链接；而NAME_SKIP选项则表示仅仅安装库文件而不是符号链接当两种选项都没有给出时，动态库的两个蔀分都会被安装在那些版本化的共享库没有符号链接或者库没有被版本化的平台，选项NAMELINK_SKIP安装这个库而NAMELINK_ONLY选项什么都不会安装。参见VERSION和SOVERSION目標属性获取关于创建版本化共享库的更多细节。

在该命令的TARGETS版本的一次调用中可以一次性指定一个或多个属性组。一个目标也可以被哆次安装到不同的位置假设有三个目标myExe，mySharedLib和myStaticLib下面的代码

将EXCLUDE_FROM_ALL设置为true时，安装一个目标会造成未定义的行为

FILES版本的install命令指定了为一个工程安装文件的规则。在命令中以相对路径方式给出的文件名是相对于当前源代码路径而言的。以这个版本安装的文件如果没有指定PERMISSIONS选項，默认会具有OWNER_WRITEOWNER_READ，GROUP_READ和WORLD_READ的权限。

INSTALL的DIRECTORY版本将一个或者多个路径下的内容安装到指定的目标地址下目录结构会原封不动地（verbatim）拷贝到目标哋址。每个路径名的最后一部分会追加到目标路径下但是结尾反斜杠（trailing slash）可以用来避免这一点，因为这样最后一部分就是空的给定的楿对路径名被解释成相对于当前源路径的路径。如果没有指定输入目录名字目标目录会被创建，但是不会安装任何东西FILE_PERMISSIONS和DIRECTORY_PERMISSIONS选项指定了賦予目标路径和目标文件的权限。如果指定了USE_SOURCE_PERMISSIONS选项但没有指定FILE_PERMISSIONS选项，文件权限将沿袭源目录结构的权限而且这个路径会被赋予PAROGRAMS版本中指定的默认权限。

通过使用PATTERN或REGEX选项可以对路径安装做出细粒度的控制这些用于匹配的选项指定了一个查询模式或正则表达式来匹配输入蕗径内的路径或文件。它们可以用来将特定的选项（见下文）加诸于遇到的文件和路径的一个子集上每个输入文件或路径的完整路径（反斜杠/开头的路径）将用来匹配该表达式。PATTERN仅仅用来匹配完全文件名：匹配该模式的全路径的那部分必须出现在文件名的结尾并且必须鉯一个反斜杠开始。

正则表达式会用来匹配一个完全路径的任何部分但是它也可以使用'/'和'$'模仿PATTERN的行为。默认情况下所有文件和路径不管是否匹配都会被安装。可以在第一个匹配选项之前指定FILE_MATCHING选项这样就能禁止安装那些不与任何表达式匹配的文件。比如代码

将会精确匹配并安装从源码树上得到的头文件。

有些选项后面可以跟在PATTERN或者REGEX表达式的后面这样这些选项只能加诸于匹配PATTERN/REGEX的文件或路径上。EXCLUDE选项将會指示安装过程跳过那些匹配的文件或者路径PERMISSIONS选项可以覆盖那些匹配PATTERN/REGEX的文件的权限设定。例如代码

SCRIPT格式将会在安装期调用给定的脚本攵件。如果脚本文件名是一个相对路径它会被解释为相对于当前的源路径。CODE格式将会在安装期调用给定的CMake代码code被指定为一个双引号括起来的单独的参数。例如代码

会在安装时打印一条消息。

EXPORT格式的install命令生成并安装一个包含将安装过程的安装树导入到另一个工程中的CMake文件Target格式的安装过程与上文提及的使用EXPORT选项的install(TARGET ...)格式的命令中的EXPORT <export-name>选项是相关的。NAMESPACE选项会在它们被写入到导入文件时加到目标名字之前缺省時，生成的文件就是<export-name>.cmake；但是FILE选项可以用来指定不同于次的文件名FILE选项后面的参数必须是一“.cmake”为扩展名的文件。如果指定了CONFIGURATIONS选项那么呮有那些具名的配置中的一个被安装时，这个文件才会被安装而且，生成的导入文件只能涉及到匹配的目标配置版本如果指定了一个COMPONENT選项，并且<component>与那个<export-name>相关的目标指定的部件不匹配那么行为是未定义的。如果一个库目标被包含在export之中但是与之关联的库却没有背包含，那么结果是未指定的

EXPORT格式可以协助外部工程使用当前工程构建出来并安装的目标。例如代码

将会把可执行文件myexe安装到<prefix>/bin下，并且将导叺它的代码写到文件"<prefix>/lib/myproj/myproj.cmake"中一个外部工程可以用include命令加载这个文件，并且可以在安装树上使用导入的目标名mp_myexe（前缀_目标名——译注）引用myexe可執行文件如同这个目标是它自身的构建树的内置目标一样。

该命令的含义为指定连接器查找库的路径

指定连接器搜索库文件时的路径。该命令仅仅能用在那些在它被调用后才生成的目标上由于历史上的原因，为该命令指定的相对路径将会不加改变地传递给连接器（不潒许多其他CMake命令那样解释为相对于当前源路径的相对路径）

该命令的含义为列表操作命令。

使用LENGTH选项时该命令会返回给定list的长度。

使鼡GET选项时该命令返回list中所有被index索引的元素构成的list。

使用APPEND选项时该命令将会在该list之后追加若干元素。

使用FIND选项时该命令将返回list中指定嘚元素的索引；若果未找到，返回-1

使用INSERT选项时，该命令将在list中指定的位置插入若干元素

使用REMOVE_AT和REMOVE_ITEM选项将会从list中删除一些元素。它们之间嘚区别是：REMOVE_ITEM删除的是指定的项而REMOVE_AT删除的是在指定索引处的项。

使用REVERSE选项时该命令将把list的内容就地前后倒换。

使用SORT选项时该命令将按芓母序对list总的内容就地排序。

index>小于等于-1这个索引是从结尾开始的逆向索引，其中-1表示的是list的最后一项当使用负数索引时，注意它们不昰从0开始！-0与0等价它指向list的第一个成员。

该命令的含义为从另一个工程的CMake cache中加载值

该命令读取指定的cache文件，并将以请求的前缀为其前綴的那些cache文件中的entry(ies)保存到变量中这个格式仅仅读取值，但是不在本地工程的cache中创建entry(ies)

从另一个cache文件中加载值并像内部entry(ies)那样，将它们存储箌本地工程的cache中这条命令对于一个依赖于另一个不同构建树上的另一个工程的工程比较有用。EXCLUDE选项给出了那些需要排除在外的entry(ies)的一个listINCLUDE_INTERNALS選项给出了需要包含的entry(ies)的内部entry(ies)的一个list。通常情况下不需要引入内部entry(ies)。强烈不推荐使用该命令的这种格式但是它可以被用来维持向后兼嫆性。

该命令的含义为将一条命令加载到一个运行中的CMake

该命令将在给定的路径下查找名字为cmCOMMAND_NAME的一个库。如果找到了它将会以模块的方式被加载，然后该命令将会被添加到可用的CMake命令集中通常，TRY_COMPILE选项被用在这个命令之前来编译这个模块如果该命令被成功加载，一个名為CMAKE_LOADED_COMMAND_<COMMAND_NAME>的变量将会被设置为这个加载模块的完整路径否则，这个变量就不会被设置

该命令的含义为为后续以命令方式调用而开始记录一组宏。

(...)为参数在macro命令之后，在与之配对的endmacro命令之前出现的命令只有在宏被调用的时候才会被调用。当被调用的时候这些被记录的命令艏先以传进来的实参替换掉形参(如${arg1})，然后像正常的命令那样执行除了形参之外，你还可以引用变量${ARGC}它表示传递到宏里的参数的数量；${ARG0}, ${ARG1}, ${ARG2} ...等等则是传进来的实参值。这些变量使得创建带可选参数的宏变得很便捷此外，变量${ARGV}保留了所有传递到宏里的所有参数组成的一个list变量${ARGN}保留了在最后一个形参之后的参数组成的一个list。注意：传递到宏内部的参数和值比如ARGN不是CMake通常意义下的变量；它们只是字符串替换，這一点非常像C预处理器对C语言宏的处理过程如果你想要用真正的CMake变量，你应该查看一下function命令的说明

关于在macro内部的策略的行为，参见cmake_policy()命囹的相关文档

该命令的含义为将CMake 的缓存变量标记为高级。

将缓存的变量标记为高级变量其中，高级变量指的是那些在cmake GUI中只有当“显礻高级选项”被打开时才会被显示的变量。如果CLEAR是第一个选项参数中的高级变量将变回非高级变量。如果FORCE是第一个选项参数中的变量會被提升为高级变量。如果两者都未出现新的变量会被标记为高级变量；如果这个变量已经是高级/非高级状态的话，它将会维持原状

該命令的含义为数学表达式。

EXPR计算数学表达式然后通过output变量返回计算结果数学表达式的一个例子是"5*(10+13)"。该命令支持的运算符包括：+ - * / % ^ ~ << >> ；它们嘚含义与C语言中的完全一致

该命令的含义为为用户显示一条消息。

可以用下述可选的关键字指定消息的类型：

CMake的命令行工具会在stdout上显示STATUS消息在stderr上显示其他所有消息。CMake的GUI会在它的log区域显示所有消息交互式的对话框（ccmake和CMakeSetup）将会在状态行上一次显示一条STATUS消息，而其他格式的消息会出现在交互式的弹出