文档

这不是最新的CMake版本。请参阅主 CMake 文档 索引以获取较新版本。
CTest 2.6 文档 是使用 ctest --help-html 从 ctest 程序生成的。ctest - ctest

主索引

名称

  ctest - Testing driver provided by CMake.

用法

  ctest [options]

描述

"ctest" 可执行文件是 CMake 测试驱动程序。为使用 ENABLE_TESTING 和 ADD_TEST 命令创建的项目创建的 CMake 生成的构建树具有测试支持。此程序将运行测试并报告结果。

选项

  • -C <cfg>, --build-config <cfg>: 选择要测试的配置。

    一些 CMake 生成的构建树可以在同一个树中具有多个构建配置。此选项可用于指定应测试哪个配置。示例配置为“Debug”和“Release”。

  • -V,--verbose: 启用测试的详细输出。

    测试输出通常会被抑制，并且仅显示摘要信息。此选项将显示所有测试输出。

  • -VV,--extra-verbose: 启用测试的更详细输出。

    测试输出通常会被抑制，并且仅显示摘要信息。此选项将显示更多测试输出。

  • --debug: 显示 CTest 的更详细内部信息。

    此功能将导致大量输出，这些输出主要用于调试仪表盘问题。

  • -Q,--quiet: 使 ctest 静默。

    此选项将抑制所有输出。如果指定了 --output-log，则仍将生成输出日志文件。如果指定了 --quiet，则会忽略 --verbose、--extra-verbose 和 --debug 等选项。

  • -O <file>, --output-log <file>: 输出到日志文件

    此选项告诉 ctest 将其所有输出写入日志文件。

  • -N,--show-only: 禁用测试的实际执行。

    此选项告诉 ctest 列出将要运行的测试，但实际上不运行它们。与 -R 和 -E 选项结合使用时很有用。

  • -R <regex>, --tests-regex <regex>: 运行与正则表达式匹配的测试。

    此选项告诉 ctest 仅运行名称与给定正则表达式匹配的测试。

  • -E <regex>, --exclude-regex <regex>: 排除与正则表达式匹配的测试。

    此选项告诉 ctest 不要运行名称与给定正则表达式匹配的测试。

  • -D <dashboard>, --dashboard <dashboard>: 执行仪表盘测试

    此选项告诉 ctest 充当 Dart 客户端并执行仪表盘测试。所有测试都是 <Mode><Test>，其中 Mode 可以是 Experimental、Nightly 和 Continuous，Test 可以是 Start、Update、Configure、Build、Test、Coverage 和 Submit。

  • -M <model>, --test-model <model>: 设置仪表盘的模型

    此选项告诉 ctest 充当 Dart 客户端，其中 TestModel 可以是 Experimental、Nightly 和 Continuous。组合 -M 和 -T 类似于 -D

  • -T <action>, --test-action <action>: 设置要执行的仪表盘操作

    此选项告诉 ctest 充当 Dart 客户端并执行某些操作，例如启动、构建、测试等。组合 -M 和 -T 类似于 -D

  • --track <track>: 指定要提交仪表盘的跟踪

    将仪表盘提交到指定的跟踪而不是默认跟踪。默认情况下，仪表盘会提交到 Nightly、Experimental 或 Continuous 跟踪，但通过指定此选项，跟踪可以是任意的。

  • -S <script>, --script <script>: 为配置执行仪表盘

    此选项告诉 ctest 加载配置脚本，该脚本设置了许多参数，例如二进制和源目录。然后 ctest 将执行创建和运行仪表盘所需的步骤。此选项基本上设置了一个仪表盘，然后使用适当的选项运行 ctest -D。

  • -SP <script>, --script-new-process <script>: 为配置执行仪表盘

    此选项执行与 -S 相同的操作，但它将在单独的进程中执行。这主要用于脚本可能修改环境并且您不希望修改后的环境影响其他 -S 脚本的情况。

  • -A <file>, --add-notes <file>: 在提交时添加注释文件

    此选项告诉 ctest 在提交仪表盘时包含注释文件。

  • -I [Start,End,Stride,test#,test#|Test file], --tests-information: 按编号运行特定数量的测试。

    此选项导致 ctest 从编号 Start 开始运行测试，到编号 End 结束，并以 Stride 递增。Stride 之后的任何其他数字都被视为单个测试编号。Start、End 或 stride 可以为空。可以选择提供一个文件，该文件包含与命令行相同的语法。

  • -U, --union: 获取 -I 和 -R 的并集

    当 -R 和 -I 都被指定时，默认情况下会运行测试的交集。通过指定 -U，将运行测试的并集。

  • --interactive-debug-mode [0|1]: 将交互模式设置为 0 或 1。

    此选项导致 ctest 以交互模式或非交互模式运行测试。在 Windows 上，这意味着在非交互模式下，所有系统调试弹出窗口都将被阻止。在仪表盘模式（Experimental、Nightly、Continuous）下，默认为非交互模式。当仅运行非仪表盘测试时，默认为允许弹出窗口和交互式调试。

  • --build-and-test: 配置、构建和运行测试。

    此选项告诉 ctest 配置（即对源代码运行 cmake）、构建和/或执行测试。配置和测试步骤是可选的。此命令行的参数是源目录和二进制目录。默认情况下，除非指定了 --build-nocmake，否则它将在指定的 Source/Bin 目录上运行 CMake。必须同时提供 --build-makeprogram 和 --build-generator 才能使用 --built-and-test。如果指定了 --test-command，则将在构建完成后运行它。其他影响此模式的选项有 --build-target --build-nocmake、--build-run-dir、--build-two-config、--build-exe-dir、--build-project、--build-noclean、--build-options

  • --build-target: 指定要构建的特定目标。

    此选项与 --build-and-test 选项一起使用，如果省略，则构建所有目标。

  • --build-nocmake: 在不先运行 cmake 的情况下运行构建。

    跳过 cmake 步骤。

  • --build-run-dir: 指定运行程序的目录。

    编译后程序所在的目录。

  • --build-two-config: 运行 CMake 两次
  • --build-exe-dir: 指定可执行文件的目录。
  • --build-generator: 指定要使用的生成器。
  • --build-project: 指定要构建的项目的名称。
  • --build-makeprogram: 指定要使用的 make 程序。
  • --build-noclean: 跳过 make clean 步骤。
  • --build-config-sample: 用于确定配置的示例可执行文件

    用于确定应使用哪个配置的示例可执行文件。例如 Debug/Release/等

  • --build-options: 向构建步骤添加额外选项。

    此选项必须是最后一个选项，--test-command 除外

  • --test-command: 与 --build-and-test 选项一起运行的测试。
  • --test-timeout: 以秒为单位的时间限制，仅供内部使用。
  • --tomorrow-tag: Nightly 或 experimental 从下一天标签开始。

    如果构建不能在一天内完成，这将很有用。

  • --ctest-config: 用于在提交仪表盘时初始化 CTest 状态的配置文件。

    此选项告诉 CTest 使用不同的初始化文件而不是 CTestConfiguration.tcl。这样，例如，可以使用多个初始化文件提交到多个仪表盘。

  • --overwrite: 覆盖 CTest 配置选项。

    默认情况下，ctest 使用配置文件中的配置选项。此选项将覆盖配置选项。

  • --extra-submit <file>[;<file>]: 将额外文件提交到仪表盘。

    此选项将额外文件提交到仪表盘。

  • --force-new-ctest-process: 作为新进程运行子 CTest 实例

    默认情况下，CTest 将在同一进程中运行子 CTest 实例。如果不需要此行为，则此参数将为子 CTest 进程强制使用新进程。

  • --submit-index: 提交具有特定索引的单个仪表盘测试

    此选项允许多次执行相同的 CTest 操作（例如测试）并将所有阶段提交到同一仪表盘（需要 Dart2）。每次执行都需要不同的索引。

生成器

此平台上提供以下生成器

命令

  • break: 从封闭的 foreach 或 while 循环中跳出。
      break()

    从封闭的 foreach 循环或 while 循环中跳出

  • build_name: 已弃用。请改用 ${CMAKE_SYSTEM} 和 ${CMAKE_CXX_COMPILER}。
      build_name(variable)

    将指定变量设置为表示平台和编译器设置的字符串。这些值现在可以通过 CMAKE_SYSTEM 和 CMAKE_CXX_COMPILER 变量获得。

  • cmake_minimum_required: 设置项目所需的 cmake 的最低版本。
      cmake_minimum_required(VERSION major[.minor[.patch]]
                             [FATAL_ERROR])

    如果当前 CMake 版本低于所需版本，它将停止处理项目并报告错误。当指定高于 2.4 的版本时，该命令隐式调用

      cmake_policy(VERSION major[.minor[.patch]])

    这将 cmake 策略版本级别设置为指定的版本。当给出 2.4 或更低版本时，该命令隐式调用

      cmake_policy(VERSION 2.4)

    这将启用 CMake 2.4 及更低版本的兼容性功能。

    CMake 2.6 及更高版本接受但忽略 FATAL_ERROR 选项。应指定它，以便 CMake 2.4 及更低版本以错误而不是警告的形式失败。

  • cmake_policy: 管理 CMake 策略设置。

    随着 CMake 的发展，有时需要更改现有行为以修复错误或改进现有功能的实现。CMake 策略机制旨在帮助保持现有项目在 CMake 的新版本引入行为更改时继续构建。每个新策略（行为更改）都将获得一个格式为“CMP<NNNN>”的标识符，其中“<NNNN>”是一个整数索引。与每个策略相关的文档描述了旧和新行为以及引入该策略的原因。项目可以设置每个策略以选择所需的行为。当 CMake 需要知道使用哪种行为时，它会检查项目指定的设置。如果未提供任何设置，则假定使用旧行为并发出警告，要求设置策略。

    cmake_policy 命令用于将策略设置为旧或新行为。虽然支持单独设置策略，但我们鼓励项目根据 CMake 版本设置策略。

      cmake_policy(VERSION major.minor[.patch])

    指定当前 CMake 列表文件是为给定版本的 CMake 编写的。指定版本或更早版本中引入的所有策略都将设置为使用新行为。指定版本之后引入的所有策略都将重置为使用旧行为并发出警告。这有效地请求了给定 CMake 版本的首选行为，并告诉更新的 CMake 版本警告其新策略。指定的策略版本必须至少为 2.4，否则命令将报告错误。为了获得支持 2.4 之前版本的兼容性功能，请参阅策略 CMP0001 的文档。

      cmake_policy(SET CMP<NNNN> NEW)
      cmake_policy(SET CMP<NNNN> OLD)

    告诉 CMake 对给定策略使用旧或新行为。依赖于给定策略旧行为的项目可以通过将策略状态设置为旧来消除策略警告。或者，可以修复项目以使用新行为并将策略状态设置为新。

      cmake_policy(GET CMP<NNNN> <variable>)

    检查给定策略是否设置为旧或新行为。如果策略已设置，则输出变量值将为“旧”或“新”，否则为空。

    CMake 在堆栈上保留策略设置，因此 cmake_policy 命令所做的更改仅影响堆栈的顶部。每个子目录都会自动管理策略堆栈上的一个新条目，以保护其父级和同级。CMake 还为 include() 和 find_package() 命令加载的脚本管理一个新条目，除非在调用时使用 NO_POLICY_SCOPE 选项（另请参阅策略 CMP0011）。cmake_policy 命令提供了一个接口来管理策略堆栈上的自定义条目

      cmake_policy(PUSH)
      cmake_policy(POP)

    每个 PUSH 都必须具有匹配的 POP 以删除任何更改。这对于对策略设置进行临时更改很有用。

    函数和宏在创建时记录策略设置，并在调用时使用预记录的策略。如果函数或宏实现设置了策略，则更改会自动向上传播到调用者，直到到达最近的嵌套策略堆栈条目。

  • configure_file: 将文件复制到另一个位置并修改其内容。
      configure_file(InputFile OutputFile
                     [COPYONLY] [ESCAPE_QUOTES] [@ONLY])

    输入和输出文件必须具有完整路径。此命令将输入文件中引用为 ${VAR} 或 @VAR@ 的任何变量替换为 CMake 确定的其值。如果未定义变量，则将其替换为空。如果指定了 COPYONLY，则不会发生任何变量扩展。如果指定了 ESCAPE_QUOTES，则任何替换的引号都将进行 C 样式转义。文件将使用 CMake 变量的当前值进行配置。如果指定了 @ONLY，则仅替换 @VAR@ 形式的变量，而忽略 ${VAR}。这对于配置使用 ${VAR} 的脚本很有用。任何 #cmakedefine VAR 的出现都将替换为 #define VAR 或 /* #undef VAR */，具体取决于 CMake 中 VAR 的设置

  • ctest_build: 构建存储库。
      ctest_build([BUILD build_dir] [RETURN_VALUE res])

    构建给定的构建目录并将结果存储在 Build.xml 中。

  • ctest_configure: 配置存储库。
      ctest_configure(BUILD build_dir RETURN_VALUE res)

    配置给定的构建目录并将结果存储在 Configure.xml 中。第二个参数是一个变量，它将保存返回值。

  • ctest_coverage: 测试存储库。
      ctest_coverage([BUILD build_dir] [RETURN_VALUE res])

    执行给定构建目录的覆盖率并将结果存储在 Coverage.xml 中。第二个参数是一个变量，它将保存值。

  • ctest_empty_binary_directory: 清空二进制目录
      ctest_empty_binary_directory( directory )

    删除二进制目录。此命令在删除目录之前会执行一些检查，以避免恶意或意外的目录删除。

  • ctest_memcheck: 测试存储库。
      ctest_memcheck([BUILD build_dir] [RETURN_VALUE res])

    执行给定构建目录中测试的内存检查并将结果存储在 MemCheck.xml 中。第二个参数是一个变量，它将保存值。

  • ctest_read_custom_files: 读取 CTestCustom 文件。
      ctest_read_custom_files( directory ... )

    从给定目录读取所有 CTestCustom.ctest 或 CTestCustom.cmake 文件。

  • ctest_run_script: 运行 ctest -S 脚本
      ctest_run_script([NEW_PROCESS] script_file_name script_file_name1 
                  script_file_name2 ...)

    运行脚本或多个脚本，就像从 ctest -S 中运行一样。如果未提供任何参数，则使用变量的当前设置运行当前脚本。如果指定了 NEW_PROCESS，则每个脚本都将在单独的进程中运行。

  • ctest_sleep: 休眠一段时间
      ctest_sleep( seconds )
      ctest_sleep( time1 duration time2 )

    使用一个参数，它将休眠给定秒数。使用三个参数，它将等待 time2 - time1 - duration 秒。

  • ctest_start: 启动给定模型的测试
      ctest_start(Model [TRACK <track>] [source [binary]])

    启动给定模型的测试。此命令应在初始化二进制目录后调用。如果未指定“源”和“二进制”目录，则读取 CTEST_SOURCE_DIRECTORY 和 CTEST_BINARY_DIRECTORY。如果指定了 track，则提交将发送到指定的 track。

  • ctest_submit: 提交存储库。
      ctest_submit([RETURN_VALUE res])

    提交项目的测试结果。

  • ctest_test: 测试存储库。
      ctest_test([BUILD build_dir]
                 [START start number] [END end number]
                 [STRIDE stride number] [EXCLUDE exclude regex ]
                 [INCLUDE include regex] [RETURN_VALUE res] )

    测试给定的构建目录并将结果存储在 Test.xml 中。第二个参数是一个变量，它将保存值。可选地，您可以指定起始测试编号 START、结束测试编号 END、每个测试之间要跳过的测试数量 STRIDE、要运行的测试的正则表达式 INCLUDE 或要运行的测试的正则表达式 EXCLUDE。

  • ctest_update: 更新存储库。
      ctest_update([SOURCE source] [RETURN_VALUE res])

    更新给定的源目录并将结果存储在 Update.xml 中。第二个参数是一个变量，它将保存已修改的文件数量。如果出现问题，则变量将为 -1。

  • else: 开始 if 块的 else 部分。
      else(expression)

    请参阅 if 命令。

  • elseif: 开始 if 块的 elseif 部分。
      elseif(expression)

    请参阅 if 命令。

  • endforeach: 结束 FOREACH 块中的一系列命令。
      endforeach(expression)

    请参阅 FOREACH 命令。

  • endfunction: 结束函数块中的一系列命令。
      endfunction(expression)

    请参阅 function 命令。

  • endif: 结束 if 块中的一系列命令。
      endif(expression)

    请参阅 if 命令。

  • endmacro: 结束宏块中的一系列命令。
      endmacro(expression)

    请参阅 macro 命令。

  • endwhile: 结束 while 块中的一系列命令。
      endwhile(expression)

    请参阅 while 命令。

  • exec_program: 已弃用。请改用 execute_process() 命令。

    在处理 CMakeList.txt 文件期间运行可执行程序。


      exec_program(Executable [directory in which to run]
                   [ARGS <arguments to executable>]
                   [OUTPUT_VARIABLE <var>]
                   [RETURN_VALUE <var>])

    可执行文件在可选指定的目录中运行。如果可执行文件用双引号括起来，则可以包含参数，但最好使用可选的 ARGS 参数来指定程序的参数。这是因为 cmake 能够转义可执行文件路径中的空格。可选参数 OUTPUT_VARIABLE 指定一个变量，用于存储输出。要捕获执行的返回值，请提供 RETURN_VALUE。如果指定了 OUTPUT_VARIABLE，则没有任何输出会发送到运行 cmake 的控制台的标准输出/标准错误。

  • execute_process：执行一个或多个子进程。
      execute_process(COMMAND <cmd1> [args1...]]
                      [COMMAND <cmd2> [args2...] [...]]
                      [WORKING_DIRECTORY <directory>]
                      [TIMEOUT <seconds>]
                      [RESULT_VARIABLE <variable>]
                      [OUTPUT_VARIABLE <variable>]
                      [ERROR_VARIABLE <variable>]
                      [INPUT_FILE <file>]
                      [OUTPUT_FILE <file>]
                      [ERROR_FILE <file>]
                      [OUTPUT_QUIET]
                      [ERROR_QUIET]
                      [OUTPUT_STRIP_TRAILING_WHITESPACE]
                      [ERROR_STRIP_TRAILING_WHITESPACE])

    运行给定的一个或多个命令序列，每个进程的标准输出都连接到下一个进程的标准输入。所有进程都使用一个标准错误管道。如果给定 WORKING_DIRECTORY，则指定的目录将被设置为子进程的当前工作目录。如果给定 TIMEOUT，则如果子进程在指定的时间（允许使用小数）内未完成，则将终止它们。如果给定 RESULT_VARIABLE，则该变量将设置为包含进程运行结果。这将是最后一个子进程的整数返回代码或描述错误条件的字符串。如果给定 OUTPUT_VARIABLE 或 ERROR_VARIABLE，则命名的变量将分别设置为标准输出和标准错误管道的內容。如果为这两个管道命名了相同的变量，则它们的输出将按产生的顺序合并。如果给定 INPUT_FILE、OUTPUT_FILE 或 ERROR_FILE，则命名的文件将分别连接到第一个进程的标准输入、最后一个进程的标准输出或所有进程的标准错误。如果给定 OUTPUT_QUIET 或 ERROR_QUIET，则标准输出或标准错误结果将被静默忽略。如果为同一个管道给出了多个 OUTPUT_* 或 ERROR_* 选项，则优先级未指定。如果没有给出 OUTPUT_* 或 ERROR_* 选项，则输出将与 CMake 进程本身的相应管道共享。

    execute_process 命令是 exec_program 的一个更新、更强大的版本，但为了兼容性保留了旧命令。

  • file：文件操作命令。
      file(WRITE filename "message to write"... )
      file(APPEND filename "message to write"... )
      file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
      file(STRINGS filename variable [LIMIT_COUNT num]
           [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
           [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
           [NEWLINE_CONSUME] [REGEX regex]
           [NO_HEX_CONVERSION])
      file(GLOB variable [RELATIVE path] [globbing expressions]...)
      file(GLOB_RECURSE variable [RELATIVE path] 
           [FOLLOW_SYMLINKS] [globbing expressions]...)
      file(REMOVE [file1 ...])
      file(REMOVE_RECURSE [file1 ...])
      file(MAKE_DIRECTORY [directory1 directory2 ...])
      file(RELATIVE_PATH variable directory file)
      file(TO_CMAKE_PATH path result)
      file(TO_NATIVE_PATH path result)
      file(DOWNLOAD url file [TIMEOUT timeout] [STATUS status] [LOG log])

    WRITE 将消息写入名为“filename”的文件。如果文件已存在，则会覆盖该文件；如果文件不存在，则会创建该文件。

    APPEND 将消息写入文件，与 WRITE 相同，只是会将其追加到文件的末尾。

    READ 读取文件的内容并将其存储到变量中。它将从给定的偏移量开始读取，最多读取 numBytes 字节。如果给定参数 HEX，则二进制数据将转换为十六进制表示形式，并将其存储在变量中。

    STRINGS 将从文件中解析 ASCII 字符串列表并将其存储在变量中。文件中的二进制数据将被忽略。回车符 (CR) 将被忽略。它也适用于 Intel Hex 和 Motorola S-record 文件，这些文件在读取时会自动转换为二进制格式。使用 NO_HEX_CONVERSION 禁用此功能。

    LIMIT_COUNT 设置要返回的最大字符串数。LIMIT_INPUT 设置从输入文件读取的最大字节数。LIMIT_OUTPUT 设置要存储在输出变量中的最大字节数。LENGTH_MINIMUM 设置要返回的字符串的最小长度。较短的字符串将被忽略。LENGTH_MAXIMUM 设置要返回的字符串的最大长度。较长的字符串将被拆分为长度不超过最大长度的字符串。NEWLINE_CONSUME 允许将换行符包含在字符串中，而不是用它们来终止字符串。

    REGEX 指定字符串必须匹配的正则表达式才能返回。典型用法

      file(STRINGS myfile.txt myfile)

    将输入文件中的每一行存储在变量“myfile”中的一个列表中。

    GLOB 将生成与通配符表达式匹配的所有文件的列表，并将其存储到变量中。通配符表达式类似于正则表达式，但要简单得多。如果为表达式指定了 RELATIVE 标志，则结果将作为相对于给定路径的相对路径返回。

    通配符表达式的示例包括

       *.cxx      - match all files with extension cxx
       *.vt?      - match all files with extension vta,...,vtz
       f[3-5].txt - match files f3.txt, f4.txt, f5.txt

    GLOB_RECURSE 将生成类似于常规 GLOB 的列表，只是它将遍历匹配目录的所有子目录并匹配文件。仅当给定 FOLLOW_SYMLINKS 或 cmake 策略 CMP0009 未设置为 NEW 时，才会遍历作为符号链接的子目录。有关更多信息，请参阅 cmake --help-policy CMP0009。

    递归通配符的示例包括

       /dir/*.py  - match all python files in /dir and subdirectories

    MAKE_DIRECTORY 将创建给定的目录，即使它们的父目录尚不存在。

    REMOVE 将删除给定的文件，包括子目录中的文件。

    REMOVE_RECURSE 将删除给定的文件和目录，包括非空目录。

    RELATIVE_PATH 将确定从目录到给定文件的相对路径。

    TO_CMAKE_PATH 将路径转换为使用 unix / 的 cmake 样式路径。输入可以是单个路径或系统路径，例如“$ENV{PATH}”。请注意 ENV 调用周围的双引号，TO_CMAKE_PATH 仅接受一个参数。

    TO_NATIVE_PATH 的工作原理与 TO_CMAKE_PATH 类似，但会将 cmake 样式路径转换为本机路径样式，对于 Windows 为 \，对于 UNIX 为 /。

    DOWNLOAD 将给定的 URL 下载到给定的文件。如果指定了 LOG 变量，则下载日志将放在变量中。如果指定了 STATUS 变量，则操作的状态将放在变量中。状态以长度为 2 的列表返回。第一个元素是操作的数字返回值，第二个元素是错误的字符串值。数字错误 0 表示操作中没有错误。如果指定了 TIMEOUT 时间，则操作将在时间秒后超时，时间可以指定为浮点数。

  • find_file：查找文件的完整路径。
       find_path(<VAR> name1 [path1 path2 ...])

    这是命令的简写签名，在许多情况下足够使用。它与 find_path(<VAR> name1 [PATHS path1 path2 ...]) 相同。

       find_path(
                 <VAR>
                 name | NAMES name1 [name2 ...]
                 [HINTS path1 [path2 ... ENV var]]
                 [PATHS path1 [path2 ... ENV var]]
                 [PATH_SUFFIXES suffix1 [suffix2 ...]]
                 [DOC "cache documentation string"]
                 [NO_DEFAULT_PATH]
                 [NO_CMAKE_ENVIRONMENT_PATH]
                 [NO_CMAKE_PATH]
                 [NO_SYSTEM_ENVIRONMENT_PATH]
                 [NO_CMAKE_SYSTEM_PATH]
                 [CMAKE_FIND_ROOT_PATH_BOTH |
                  ONLY_CMAKE_FIND_ROOT_PATH |
                  NO_CMAKE_FIND_ROOT_PATH]
                )

    此命令用于查找命名文件的完整路径。将创建名为 <VAR> 的缓存条目以存储此命令的结果。如果找到文件的完整路径，则结果将存储在变量中，并且除非清除变量，否则不会重复搜索。如果未找到任何内容，则结果将为 <VAR>-NOTFOUND，并且下次使用相同变量调用 find_path 时将再次尝试搜索。要搜索的文件的完整路径名称由 NAMES 参数后面列出的名称指定。可以在 PATHS 参数后面指定其他搜索位置。如果在 HINTS 或 PATHS 部分中找到 ENV 变量，则将读取环境变量并将其从系统环境变量转换为 cmake 样式的路径列表。例如，ENV PATH 将是列出系统路径变量的一种方法。DOC 后面的参数将用于缓存中的文档字符串。PATH_SUFFIXES 指定要检查每个搜索路径下方的其他子目录。

    如果指定了 NO_DEFAULT_PATH，则不会向搜索添加其他路径。如果未指定 NO_DEFAULT_PATH，则搜索过程如下

    1. 搜索 cmake 特定缓存变量中指定的路径。这些路径旨在与命令行一起使用，使用 -DVAR=value。如果传递了 NO_CMAKE_PATH，则可以跳过此步骤。

       <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
       CMAKE_INCLUDE_PATH
       CMAKE_FRAMEWORK_PATH

    2. 搜索 cmake 特定环境变量中指定的路径。这些路径旨在在用户的 shell 配置中设置。如果传递了 NO_CMAKE_ENVIRONMENT_PATH，则可以跳过此步骤。

       <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
       CMAKE_INCLUDE_PATH
       CMAKE_FRAMEWORK_PATH

    3. 搜索 HINTS 选项指定的路径。这些路径应是通过系统自省计算出的路径，例如由已找到的其他项目的地址提供的提示。硬编码的猜测应使用 PATHS 选项指定。

    4. 搜索标准系统环境变量。如果 NO_SYSTEM_ENVIRONMENT_PATH 是参数，则可以跳过此步骤。

       PATH
       INCLUDE

    5. 搜索当前系统平台文件中定义的 cmake 变量。如果传递了 NO_CMAKE_SYSTEM_PATH，则可以跳过此步骤。

       <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
       CMAKE_SYSTEM_INCLUDE_PATH
       CMAKE_SYSTEM_FRAMEWORK_PATH

    6. 搜索 PATHS 选项或命令的简写版本中指定的路径。这些通常是硬编码的猜测。

    在 Darwin 或支持 OS X 框架的系统上，可以将 cmake 变量 CMAKE_FIND_FRAMEWORK 设置为空或以下值之一

       "FIRST"  - Try to find frameworks before standard
                  libraries or headers. This is the default on Darwin.
       "LAST"   - Try to find frameworks after standard
                  libraries or headers.
       "ONLY"   - Only try to find frameworks.
       "NEVER". - Never try to find frameworks.

    在 Darwin 或支持 OS X 应用程序包的系统上，可以将 cmake 变量 CMAKE_FIND_APPBUNDLE 设置为空或以下值之一

       "FIRST"  - Try to find application bundles before standard
                  programs. This is the default on Darwin.
       "LAST"   - Try to find application bundles after standard
                  programs.
       "ONLY"   - Only try to find application bundles.
       "NEVER". - Never try to find application bundles.

    CMake 变量 CMAKE_FIND_ROOT_PATH 指定一个或多个要预先添加到所有其他搜索目录的目录。这有效地将整个搜索“重新根植”到给定位置。默认情况下，它是空的。它在交叉编译时特别有用，用于指向目标环境的根目录，并且 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，则仅搜索重新根植的目录。

    默认搜索顺序旨在针对常见用例最具体到最不具体。项目可以通过简单地多次调用命令并使用 NO_* 选项来覆盖顺序。

       find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
       find_path(<VAR> NAMES name)

    一旦其中一个调用成功，结果变量将被设置并存储在缓存中，以便不会再进行任何搜索。

  • find_library：查找库。
       find_library(<VAR> name1 [path1 path2 ...])

    这是命令的简写签名，在许多情况下足够使用。它与 find_library(<VAR> name1 [PATHS path1 path2 ...]) 相同。

       find_library(
                 <VAR>
                 name | NAMES name1 [name2 ...]
                 [HINTS path1 [path2 ... ENV var]]
                 [PATHS path1 [path2 ... ENV var]]
                 [PATH_SUFFIXES suffix1 [suffix2 ...]]
                 [DOC "cache documentation string"]
                 [NO_DEFAULT_PATH]
                 [NO_CMAKE_ENVIRONMENT_PATH]
                 [NO_CMAKE_PATH]
                 [NO_SYSTEM_ENVIRONMENT_PATH]
                 [NO_CMAKE_SYSTEM_PATH]
                 [CMAKE_FIND_ROOT_PATH_BOTH |
                  ONLY_CMAKE_FIND_ROOT_PATH |
                  NO_CMAKE_FIND_ROOT_PATH]
                )

    此命令用于查找库。将创建名为 <VAR> 的缓存条目以存储此命令的结果。如果找到库，则结果将存储在变量中，并且除非清除变量，否则不会重复搜索。如果未找到任何内容，则结果将为 <VAR>-NOTFOUND，并且下次使用相同变量调用 find_library 时将再次尝试搜索。要搜索的库的名称由 NAMES 参数后面列出的名称指定。可以在 PATHS 参数后面指定其他搜索位置。如果在 HINTS 或 PATHS 部分中找到 ENV 变量，则将读取环境变量并将其从系统环境变量转换为 cmake 样式的路径列表。例如，ENV PATH 将是列出系统路径变量的一种方法。DOC 后面的参数将用于缓存中的文档字符串。PATH_SUFFIXES 指定要检查每个搜索路径下方的其他子目录。

    如果指定了 NO_DEFAULT_PATH，则不会向搜索添加其他路径。如果未指定 NO_DEFAULT_PATH，则搜索过程如下

    1. 搜索 cmake 特定缓存变量中指定的路径。这些路径旨在与命令行一起使用，使用 -DVAR=value。如果传递了 NO_CMAKE_PATH，则可以跳过此步骤。

       <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
       CMAKE_LIBRARY_PATH
       CMAKE_FRAMEWORK_PATH

    2. 搜索 cmake 特定环境变量中指定的路径。这些路径旨在在用户的 shell 配置中设置。如果传递了 NO_CMAKE_ENVIRONMENT_PATH，则可以跳过此步骤。

       <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
       CMAKE_LIBRARY_PATH
       CMAKE_FRAMEWORK_PATH

    3. 搜索 HINTS 选项指定的路径。这些路径应是通过系统自省计算出的路径，例如由已找到的其他项目的地址提供的提示。硬编码的猜测应使用 PATHS 选项指定。

    4. 搜索标准系统环境变量。如果 NO_SYSTEM_ENVIRONMENT_PATH 是参数，则可以跳过此步骤。

       PATH
       LIB

    5. 搜索当前系统平台文件中定义的 cmake 变量。如果传递了 NO_CMAKE_SYSTEM_PATH，则可以跳过此步骤。

       <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
       CMAKE_SYSTEM_LIBRARY_PATH
       CMAKE_SYSTEM_FRAMEWORK_PATH

    6. 搜索 PATHS 选项或命令的简写版本中指定的路径。这些通常是硬编码的猜测。

    在 Darwin 或支持 OS X 框架的系统上，可以将 cmake 变量 CMAKE_FIND_FRAMEWORK 设置为空或以下值之一

       "FIRST"  - Try to find frameworks before standard
                  libraries or headers. This is the default on Darwin.
       "LAST"   - Try to find frameworks after standard
                  libraries or headers.
       "ONLY"   - Only try to find frameworks.
       "NEVER". - Never try to find frameworks.

    在 Darwin 或支持 OS X 应用程序包的系统上，可以将 cmake 变量 CMAKE_FIND_APPBUNDLE 设置为空或以下值之一

       "FIRST"  - Try to find application bundles before standard
                  programs. This is the default on Darwin.
       "LAST"   - Try to find application bundles after standard
                  programs.
       "ONLY"   - Only try to find application bundles.
       "NEVER". - Never try to find application bundles.

    CMake 变量 CMAKE_FIND_ROOT_PATH 指定一个或多个目录，这些目录将被预先添加到所有其他搜索目录之前。这实际上是在给定位置下“重新设置根目录”整个搜索范围。默认情况下它为空。在交叉编译时，它特别有用，可以指向目标环境的根目录，CMake 也会在那里搜索。默认情况下，首先搜索 CMAKE_FIND_ROOT_PATH 中列出的目录，然后搜索非根目录。可以通过设置 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY 来调整默认行为。此行为可以在每次调用时手动覆盖。通过使用 CMAKE_FIND_ROOT_PATH_BOTH，搜索顺序将如上所述。如果使用 NO_CMAKE_FIND_ROOT_PATH，则不会使用 CMAKE_FIND_ROOT_PATH。如果使用 ONLY_CMAKE_FIND_ROOT_PATH，则只会搜索重新设置根目录的目录。

    默认搜索顺序旨在针对常见用例最具体到最不具体。项目可以通过简单地多次调用命令并使用 NO_* 选项来覆盖顺序。

       find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
       find_library(<VAR> NAMES name)

    一旦其中一个调用成功，结果变量将被设置并存储在缓存中，以便不会再进行任何搜索。

    如果找到的库是框架，则 VAR 将设置为框架的完整路径 <fullPath>/A.framework。当使用框架的完整路径作为库时，CMake 将使用 -framework A 和 -F<fullPath> 将框架链接到目标。

  • find_package: 加载外部项目的设置。
      find_package(<package> [version] [EXACT] [QUIET]
                   [[REQUIRED|COMPONENTS] [components...]]
                   [NO_POLICY_SCOPE])

    查找并加载来自外部项目的设置。<package>_FOUND 将设置为指示是否找到该包。当找到包时，包特定的信息将通过包本身记录的变量提供。QUIET 选项在找不到包时禁用消息。REQUIRED 选项在找不到包时停止处理并显示错误消息。包特定的组件列表可以在 REQUIRED 选项之后列出，或者如果未给出 COMPONENTS 选项，则可以在 COMPONENTS 选项之后列出。[version] 参数请求与找到的包兼容的版本（格式为 major[.minor[.patch[.tweak]]]）。EXACT 选项请求精确匹配版本。如果在 find-module 内部的递归调用中未给出 [version]，则 [version] 和 EXACT 参数将从外部调用自动转发。版本支持目前仅在逐个包的基础上提供（详细信息如下）。

    用户代码通常应该使用上述简单签名来查找包。此命令文档的其余部分指定了完整的命令签名和搜索过程的详细信息。希望提供可通过此命令找到的包的项目维护者建议继续阅读。

    该命令有两种搜索包的模式：“模块”模式和“配置”模式。当使用上述简化签名调用该命令时，可以使用模块模式。CMake 在 CMAKE_MODULE_PATH 之后以及 CMake 安装目录中搜索名为“Find<package>.cmake”的文件。如果找到该文件，则 CMake 会读取并处理它。它负责查找包、检查版本以及生成任何需要的消息。许多 find-module 对版本控制的支持有限或没有支持；请查看模块文档。如果找不到模块，则命令将继续执行配置模式。

    完整的配置模式命令签名为

      find_package(<package> [version] [EXACT] [QUIET]
                   [[REQUIRED|COMPONENTS] [components...]] [NO_MODULE]
                   [NO_POLICY_SCOPE]
                   [NAMES name1 [name2 ...]]
                   [CONFIGS config1 [config2 ...]]
                   [HINTS path1 [path2 ... ]]
                   [PATHS path1 [path2 ... ]]
                   [PATH_SUFFIXES suffix1 [suffix2 ...]]
                   [NO_DEFAULT_PATH]
                   [NO_CMAKE_ENVIRONMENT_PATH]
                   [NO_CMAKE_PATH]
                   [NO_SYSTEM_ENVIRONMENT_PATH]
                   [NO_CMAKE_BUILDS_PATH]
                   [NO_CMAKE_SYSTEM_PATH]
                   [CMAKE_FIND_ROOT_PATH_BOTH |
                    ONLY_CMAKE_FIND_ROOT_PATH |
                    NO_CMAKE_FIND_ROOT_PATH])

    NO_MODULE 选项可用于显式跳过模块模式。使用简化签名中未指定的选项也会隐含此选项。

    配置模式尝试查找要查找的包提供的配置文件。将创建一个名为 <package>_DIR 的缓存条目，以保存包含该文件的目录。默认情况下，该命令搜索名为 <package> 的包。如果给出 NAMES 选项，则其后的名称将代替 <package> 使用。该命令搜索名为“<name>Config.cmake”或“<lower-case-name>-config.cmake”的文件，用于指定的每个名称。可以使用 CONFIGS 选项提供一组替换的可能的配置文件名称。搜索过程如下所述。找到后，CMake 会读取并处理配置文件。由于该文件由包提供，因此它已经知道包内容的位置。配置文件的完整路径存储在 cmake 变量 <package>_CONFIG 中。

    如果找不到包配置文件，CMake 将生成一个描述问题的错误，除非指定了 QUIET 参数。如果指定了 REQUIRED 且未找到包，则会生成致命错误，并且配置步骤停止执行。如果 <package>_DIR 已设置为不包含配置文件的目录，则 CMake 将忽略它并从头开始搜索。

    当给出 [version] 参数时，配置模式只会找到声称与请求的版本兼容的包版本（格式为 major[.minor[.patch[.tweak]]]）。如果给出 EXACT 选项，则只能找到声称与请求的版本完全匹配的包版本。CMake 没有为版本号的含义建立任何约定。包版本号由包本身提供的“版本”文件检查。对于候选包配置文件“<config-file>.cmake”，相应的版本文件位于其旁边，并命名为“<config-file>-version.cmake”或“<config-file>Version.cmake”。如果没有这样的版本文件，则假定配置文件与任何请求的版本都不兼容。找到版本文件后，将加载它以检查请求的版本号。版本文件在嵌套作用域中加载，其中已定义以下变量

      PACKAGE_FIND_NAME          = the <package> name
      PACKAGE_FIND_VERSION       = full requested version string
      PACKAGE_FIND_VERSION_MAJOR = major version if requested, else 0
      PACKAGE_FIND_VERSION_MINOR = minor version if requested, else 0
      PACKAGE_FIND_VERSION_PATCH = patch version if requested, else 0
      PACKAGE_FIND_VERSION_TWEAK = tweak version if requested, else 0
      PACKAGE_FIND_VERSION_COUNT = number of version components, 0 to 4

    版本文件检查它是否满足请求的版本并设置以下变量

      PACKAGE_VERSION            = full provided version string
      PACKAGE_VERSION_EXACT      = true if version is exact match
      PACKAGE_VERSION_COMPATIBLE = true if version is compatible
      PACKAGE_VERSION_UNSUITABLE = true if unsuitable as any version

    find_package 命令检查这些变量以确定配置文件是否提供可接受的版本。在 find_package 调用返回后，这些变量不可用。如果版本可接受，则将设置以下变量

      <package>_VERSION       = full provided version string
      <package>_VERSION_MAJOR = major version if provided, else 0
      <package>_VERSION_MINOR = minor version if provided, else 0
      <package>_VERSION_PATCH = patch version if provided, else 0
      <package>_VERSION_TWEAK = tweak version if provided, else 0
      <package>_VERSION_COUNT = number of version components, 0 to 4

    并加载相应的包配置文件。当多个包配置文件的版本文件声称与请求的版本兼容时，选择哪个文件是不确定的。不会尝试选择最高或最接近的版本号。

    配置模式提供了一个详细的接口和搜索过程。大部分接口是为了完整性和 find-module（由模块模式加载）内部使用而提供的。大多数用户代码应该简单地调用

      find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])

    以查找包。提供 CMake 包配置文件的包维护者建议命名和安装它们，以便以下概述的过程能够在不需要使用其他选项的情况下找到它们。

    CMake 为包构建一组可能的安装前缀。在每个前缀下，都会搜索几个目录以查找配置文件。下表显示了搜索的目录。每个条目都适用于遵循 Windows (W)、UNIX (U) 或 Apple (A) 约定的安装树。

      <prefix>/                                               (W)
      <prefix>/(cmake|CMake)/                                 (W)
      <prefix>/<name>*/                                       (W)
      <prefix>/<name>*/(cmake|CMake)/                         (W)
      <prefix>/(share|lib)/cmake/<name>*/                     (U)
      <prefix>/(share|lib)/<name>*/                           (U)
      <prefix>/(share|lib)/<name>*/(cmake|CMake)/             (U)

    在支持 OS X 框架和应用程序包的系统上，将搜索以下目录以查找包含配置文件的框架或包

      <prefix>/<name>.framework/Resources/                    (A)
      <prefix>/<name>.framework/Resources/CMake/              (A)
      <prefix>/<name>.framework/Versions/*/Resources/         (A)
      <prefix>/<name>.framework/Versions/*/Resources/CMake/   (A)
      <prefix>/<name>.app/Contents/Resources/                 (A)
      <prefix>/<name>.app/Contents/Resources/CMake/           (A)

    在所有情况下，<name> 都被视为不区分大小写，并且对应于指定的任何名称（<package> 或 NAMES 给出的名称）。如果指定了 PATH_SUFFIXES，则这些后缀将逐个附加到每个 (W) 或 (U) 目录条目。

    此目录集旨在与在其安装树中提供配置文件的项目协同工作。上面标记为 (W) 的目录用于 Windows 上的安装，其中前缀可能指向应用程序安装目录的顶部。标记为 (U) 的目录用于 UNIX 平台上的安装，其中前缀由多个包共享。这仅仅是一种约定，因此所有 (W) 和 (U) 目录仍在所有平台上搜索。标记为 (A) 的目录用于 Apple 平台上的安装。cmake 变量 CMAKE_FIND_FRAMEWORK 和 CMAKE_FIND_APPBUNDLE 确定首选项顺序，如下所示。

    使用以下步骤构建安装前缀集。如果指定了 NO_DEFAULT_PATH，则所有 NO_* 选项都将启用。

    1. 搜索 cmake 特定缓存变量中指定的路径。这些路径旨在与命令行一起使用，使用 -DVAR=value。如果传递了 NO_CMAKE_PATH，则可以跳过此步骤。

       CMAKE_PREFIX_PATH
       CMAKE_FRAMEWORK_PATH
       CMAKE_APPBUNDLE_PATH

    2. 搜索 cmake 特定环境变量中指定的路径。这些路径旨在在用户的 shell 配置中设置。如果传递了 NO_CMAKE_ENVIRONMENT_PATH，则可以跳过此步骤。

       CMAKE_PREFIX_PATH
       CMAKE_FRAMEWORK_PATH
       CMAKE_APPBUNDLE_PATH

    3. 搜索 HINTS 选项指定的路径。这些路径应由系统内省计算，例如由已找到的其他项目的找到位置提供的提示。硬编码的猜测应使用 PATHS 选项指定。

    4. 搜索标准系统环境变量。如果传递了 NO_SYSTEM_ENVIRONMENT_PATH，则可以跳过此步骤。以“/bin”或“/sbin”结尾的路径条目将自动转换为其父目录。

       PATH

    5. 搜索最近在 CMake GUI 中配置的项目构建树。如果传递了 NO_CMAKE_BUILDS_PATH，则可以跳过此步骤。这适用于用户依次构建多个依赖项目的情况。

    6. 搜索当前系统平台文件中定义的 cmake 变量。如果传递了 NO_CMAKE_SYSTEM_PATH，则可以跳过此步骤。

       CMAKE_SYSTEM_PREFIX_PATH
       CMAKE_SYSTEM_FRAMEWORK_PATH
       CMAKE_SYSTEM_APPBUNDLE_PATH

    7. 搜索 PATHS 选项指定的路径。这些通常是硬编码的猜测。

    在 Darwin 或支持 OS X 框架的系统上，可以将 cmake 变量 CMAKE_FIND_FRAMEWORK 设置为空或以下值之一

       "FIRST"  - Try to find frameworks before standard
                  libraries or headers. This is the default on Darwin.
       "LAST"   - Try to find frameworks after standard
                  libraries or headers.
       "ONLY"   - Only try to find frameworks.
       "NEVER". - Never try to find frameworks.

    在 Darwin 或支持 OS X 应用程序包的系统上，可以将 cmake 变量 CMAKE_FIND_APPBUNDLE 设置为空或以下值之一

       "FIRST"  - Try to find application bundles before standard
                  programs. This is the default on Darwin.
       "LAST"   - Try to find application bundles after standard
                  programs.
       "ONLY"   - Only try to find application bundles.
       "NEVER". - Never try to find application bundles.

    CMake 变量 CMAKE_FIND_ROOT_PATH 指定一个或多个目录，这些目录将被预先添加到所有其他搜索目录之前。这实际上是在给定位置下“重新设置根目录”整个搜索范围。默认情况下它为空。在交叉编译时，它特别有用，可以指向目标环境的根目录，CMake 也会在那里搜索。默认情况下，首先搜索 CMAKE_FIND_ROOT_PATH 中列出的目录，然后搜索非根目录。可以通过设置 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE 来调整默认行为。此行为可以在每次调用时手动覆盖。通过使用 CMAKE_FIND_ROOT_PATH_BOTH，搜索顺序将如上所述。如果使用 NO_CMAKE_FIND_ROOT_PATH，则不会使用 CMAKE_FIND_ROOT_PATH。如果使用 ONLY_CMAKE_FIND_ROOT_PATH，则只会搜索重新设置根目录的目录。

    默认搜索顺序旨在针对常见用例最具体到最不具体。项目可以通过简单地多次调用命令并使用 NO_* 选项来覆盖顺序。

       find_package(<package> PATHS paths... NO_DEFAULT_PATH)
       find_package(<package>)

    一旦其中一个调用成功，结果变量将被设置并存储在缓存中，以便不会再进行任何搜索。

    有关 NO_POLICY_SCOPE 选项的讨论，请参阅 cmake_policy() 命令文档。

  • find_path: 查找包含文件的目录。


       find_path(<VAR> name1 [path1 path2 ...])

    这是命令的简写签名，在许多情况下足够使用。它与 find_path(<VAR> name1 [PATHS path1 path2 ...]) 相同。

       find_path(
                 <VAR>
                 name | NAMES name1 [name2 ...]
                 [HINTS path1 [path2 ... ENV var]]
                 [PATHS path1 [path2 ... ENV var]]
                 [PATH_SUFFIXES suffix1 [suffix2 ...]]
                 [DOC "cache documentation string"]
                 [NO_DEFAULT_PATH]
                 [NO_CMAKE_ENVIRONMENT_PATH]
                 [NO_CMAKE_PATH]
                 [NO_SYSTEM_ENVIRONMENT_PATH]
                 [NO_CMAKE_SYSTEM_PATH]
                 [CMAKE_FIND_ROOT_PATH_BOTH |
                  ONLY_CMAKE_FIND_ROOT_PATH |
                  NO_CMAKE_FIND_ROOT_PATH]
                )

    此命令用于查找包含指定文件的目录。会创建一个名为<VAR>的缓存条目来存储此命令的结果。如果在某个目录中找到了文件，则结果将存储在变量中，并且除非清除变量，否则不会重复搜索。如果未找到任何内容，则结果将为<VAR>-NOTFOUND，并且下次使用相同变量调用find_path时将再次尝试搜索。要搜索的目录中文件的名称由NAMES参数后列出的名称指定。可以在PATHS参数后指定其他搜索位置。如果在HINTS或PATHS部分中找到ENV var，则会读取环境变量var，并将其从系统环境变量转换为cmake样式的路径列表。例如，ENV PATH将是列出系统路径变量的一种方式。DOC之后的参数将用于缓存中的文档字符串。PATH_SUFFIXES指定在每个搜索路径下要检查的其他子目录。

    如果指定了 NO_DEFAULT_PATH，则不会向搜索添加其他路径。如果未指定 NO_DEFAULT_PATH，则搜索过程如下

    1. 搜索 cmake 特定缓存变量中指定的路径。这些路径旨在与命令行一起使用，使用 -DVAR=value。如果传递了 NO_CMAKE_PATH，则可以跳过此步骤。

       <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
       CMAKE_INCLUDE_PATH
       CMAKE_FRAMEWORK_PATH

    2. 搜索 cmake 特定环境变量中指定的路径。这些路径旨在在用户的 shell 配置中设置。如果传递了 NO_CMAKE_ENVIRONMENT_PATH，则可以跳过此步骤。

       <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
       CMAKE_INCLUDE_PATH
       CMAKE_FRAMEWORK_PATH

    3. 搜索 HINTS 选项指定的路径。这些路径应是通过系统自省计算出的路径，例如由已找到的其他项目的地址提供的提示。硬编码的猜测应使用 PATHS 选项指定。

    4. 搜索标准系统环境变量。如果 NO_SYSTEM_ENVIRONMENT_PATH 是参数，则可以跳过此步骤。

       PATH
       INCLUDE

    5. 搜索当前系统平台文件中定义的 cmake 变量。如果传递了 NO_CMAKE_SYSTEM_PATH，则可以跳过此步骤。

       <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
       CMAKE_SYSTEM_INCLUDE_PATH
       CMAKE_SYSTEM_FRAMEWORK_PATH

    6. 搜索 PATHS 选项或命令的简写版本中指定的路径。这些通常是硬编码的猜测。

    在 Darwin 或支持 OS X 框架的系统上，可以将 cmake 变量 CMAKE_FIND_FRAMEWORK 设置为空或以下值之一

       "FIRST"  - Try to find frameworks before standard
                  libraries or headers. This is the default on Darwin.
       "LAST"   - Try to find frameworks after standard
                  libraries or headers.
       "ONLY"   - Only try to find frameworks.
       "NEVER". - Never try to find frameworks.

    在 Darwin 或支持 OS X 应用程序包的系统上，可以将 cmake 变量 CMAKE_FIND_APPBUNDLE 设置为空或以下值之一

       "FIRST"  - Try to find application bundles before standard
                  programs. This is the default on Darwin.
       "LAST"   - Try to find application bundles after standard
                  programs.
       "ONLY"   - Only try to find application bundles.
       "NEVER". - Never try to find application bundles.

    CMake 变量 CMAKE_FIND_ROOT_PATH 指定一个或多个要预先添加到所有其他搜索目录的目录。这有效地将整个搜索“重新根植”到给定位置。默认情况下，它是空的。它在交叉编译时特别有用，用于指向目标环境的根目录，并且 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，则仅搜索重新根植的目录。

    默认搜索顺序旨在针对常见用例最具体到最不具体。项目可以通过简单地多次调用命令并使用 NO_* 选项来覆盖顺序。

       find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
       find_path(<VAR> NAMES name)

    一旦其中一个调用成功，结果变量将被设置并存储在缓存中，以便不会再进行任何搜索。

    在搜索框架时，如果文件指定为A/b.h，则框架搜索将查找A.framework/Headers/b.h。如果找到该文件，则路径将设置为框架的路径。CMake会将其转换为正确的-F选项以包含该文件。

  • find_program: 查找可执行程序。
       find_program(<VAR> name1 [path1 path2 ...])

    这是命令的简写签名，在许多情况下都足够了。它与find_program(<VAR> name1 [PATHS path1 path2 ...])相同。

       find_program(
                 <VAR>
                 name | NAMES name1 [name2 ...]
                 [HINTS path1 [path2 ... ENV var]]
                 [PATHS path1 [path2 ... ENV var]]
                 [PATH_SUFFIXES suffix1 [suffix2 ...]]
                 [DOC "cache documentation string"]
                 [NO_DEFAULT_PATH]
                 [NO_CMAKE_ENVIRONMENT_PATH]
                 [NO_CMAKE_PATH]
                 [NO_SYSTEM_ENVIRONMENT_PATH]
                 [NO_CMAKE_SYSTEM_PATH]
                 [CMAKE_FIND_ROOT_PATH_BOTH |
                  ONLY_CMAKE_FIND_ROOT_PATH |
                  NO_CMAKE_FIND_ROOT_PATH]
                )

    此命令用于查找程序。会创建一个名为<VAR>的缓存条目来存储此命令的结果。如果找到程序，则结果将存储在变量中，并且除非清除变量，否则不会重复搜索。如果未找到任何内容，则结果将为<VAR>-NOTFOUND，并且下次使用相同变量调用find_program时将再次尝试搜索。要搜索的程序的名称由NAMES参数后列出的名称指定。可以在PATHS参数后指定其他搜索位置。如果在HINTS或PATHS部分中找到ENV var，则会读取环境变量var，并将其从系统环境变量转换为cmake样式的路径列表。例如，ENV PATH将是列出系统路径变量的一种方式。DOC之后的参数将用于缓存中的文档字符串。PATH_SUFFIXES指定在每个搜索路径下要检查的其他子目录。

    如果指定了 NO_DEFAULT_PATH，则不会向搜索添加其他路径。如果未指定 NO_DEFAULT_PATH，则搜索过程如下

    1. 搜索 cmake 特定缓存变量中指定的路径。这些路径旨在与命令行一起使用，使用 -DVAR=value。如果传递了 NO_CMAKE_PATH，则可以跳过此步骤。

       <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
       CMAKE_PROGRAM_PATH
       CMAKE_APPBUNDLE_PATH

    2. 搜索 cmake 特定环境变量中指定的路径。这些路径旨在在用户的 shell 配置中设置。如果传递了 NO_CMAKE_ENVIRONMENT_PATH，则可以跳过此步骤。

       <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
       CMAKE_PROGRAM_PATH
       CMAKE_APPBUNDLE_PATH

    3. 搜索 HINTS 选项指定的路径。这些路径应是通过系统自省计算出的路径，例如由已找到的其他项目的地址提供的提示。硬编码的猜测应使用 PATHS 选项指定。

    4. 搜索标准系统环境变量。如果 NO_SYSTEM_ENVIRONMENT_PATH 是参数，则可以跳过此步骤。

       PATH

    5. 搜索当前系统平台文件中定义的 cmake 变量。如果传递了 NO_CMAKE_SYSTEM_PATH，则可以跳过此步骤。

       <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
       CMAKE_SYSTEM_PROGRAM_PATH
       CMAKE_SYSTEM_APPBUNDLE_PATH

    6. 搜索 PATHS 选项或命令的简写版本中指定的路径。这些通常是硬编码的猜测。

    在 Darwin 或支持 OS X 框架的系统上，可以将 cmake 变量 CMAKE_FIND_FRAMEWORK 设置为空或以下值之一

       "FIRST"  - Try to find frameworks before standard
                  libraries or headers. This is the default on Darwin.
       "LAST"   - Try to find frameworks after standard
                  libraries or headers.
       "ONLY"   - Only try to find frameworks.
       "NEVER". - Never try to find frameworks.

    在 Darwin 或支持 OS X 应用程序包的系统上，可以将 cmake 变量 CMAKE_FIND_APPBUNDLE 设置为空或以下值之一

       "FIRST"  - Try to find application bundles before standard
                  programs. This is the default on Darwin.
       "LAST"   - Try to find application bundles after standard
                  programs.
       "ONLY"   - Only try to find application bundles.
       "NEVER". - Never try to find application bundles.

    CMake变量CMAKE_FIND_ROOT_PATH指定一个或多个目录，这些目录将被附加到所有其他搜索目录之前。这有效地将整个搜索“重新根植”到给定的位置。默认情况下为空。在交叉编译时，它特别有用，用于指向目标环境的根目录，并且CMake也会在那里搜索。默认情况下，首先搜索CMAKE_FIND_ROOT_PATH中列出的目录，然后搜索非根目录。可以通过设置CMAKE_FIND_ROOT_PATH_MODE_PROGRAM来调整默认行为。此行为可以在每次调用时手动覆盖。通过使用CMAKE_FIND_ROOT_PATH_BOTH，搜索顺序将如上所述。如果使用NO_CMAKE_FIND_ROOT_PATH，则不会使用CMAKE_FIND_ROOT_PATH。如果使用ONLY_CMAKE_FIND_ROOT_PATH，则只会搜索重新根植的目录。

    默认搜索顺序旨在针对常见用例最具体到最不具体。项目可以通过简单地多次调用命令并使用 NO_* 选项来覆盖顺序。

       find_program(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
       find_program(<VAR> NAMES name)

    一旦其中一个调用成功，结果变量将被设置并存储在缓存中，以便不会再进行任何搜索。

  • foreach: 对列表中的每个值评估一组命令。
      foreach(loop_var arg1 arg2 ...)
        COMMAND1(ARGS ...)
        COMMAND2(ARGS ...)
        ...
      endforeach(loop_var)
      foreach(loop_var RANGE total)
      foreach(loop_var RANGE start stop [step])

    foreach和匹配的endforeach之间的所有命令都会被记录，但不会被调用。一旦评估了endforeach，则会为原始foreach命令中列出的每个参数调用一次记录的命令列表。在每次循环迭代之前，"${loop_var}"将被设置为一个变量，其值为列表中的当前值。

    Foreach还可以迭代生成的数字范围。此迭代有三种类型

    * 指定单个数字时，范围将包含元素0到“total”。

    * 指定两个数字时，范围将包含从第一个数字到第二个数字的元素。

    * 第三个可选数字是用于从第一个数字迭代到第二个数字的增量。

  • function: 开始记录函数，以便以后作为命令调用。
      function(<name> [arg1 [arg2 [arg3 ...]]])
        COMMAND1(ARGS ...)
        COMMAND2(ARGS ...)
        ...
      endfunction(<name>)

    定义一个名为<name>的函数，该函数接受名为arg1 arg2 arg3(...)的参数。列在function之后但endfunction之前 的命令在函数被调用之前不会被调用。当它被调用时，函数中记录的命令首先通过用传递的参数替换形式参数（${arg1}）进行修改，然后像普通命令一样调用。除了引用形式参数外，还可以引用变量ARGC，它将设置为传递给函数的参数数量，以及ARGV0 ARGV1 ARGV2 ...，它们将包含传递的参数的实际值。这有助于创建具有可选参数的函数。此外，ARGV保存传递给函数的所有参数的列表，ARGN保存传递给最后一个预期参数后的所有参数的列表。

    有关函数内部策略的行为，请参阅cmake_policy()命令文档。

  • get_cmake_property: 获取CMake实例的属性。
      get_cmake_property(VAR property)

    从CMake实例获取属性。属性的值存储在变量VAR中。如果未找到该属性，CMake将报告错误。一些受支持的属性包括：VARIABLES、CACHE_VARIABLES、COMMANDS、MACROS和COMPONENTS。

  • get_directory_property: 获取目录的属性。
      get_directory_property(VAR [DIRECTORY dir] property)

    从目录获取属性。属性的值存储在变量VAR中。如果未找到该属性，CMake将报告错误。属性包括：VARIABLES、CACHE_VARIABLES、COMMANDS、MACROS、INCLUDE_DIRECTORIES、LINK_DIRECTORIES、DEFINITIONS、INCLUDE_REGULAR_EXPRESSION、LISTFILE_STACK、PARENT_DIRECTORY和DEFINITION varname。如果提供了DIRECTORY参数，则将检索提供的目录的属性，而不是当前目录的属性。只有在cmake遍历目录期间或之后，才能获取目录的属性。

  • get_filename_component: 获取完整文件名中的特定组件。
      get_filename_component(VarName FileName
                             PATH|ABSOLUTE|NAME|EXT|NAME_WE
                             [CACHE])

    将VarName设置为FileName的路径（PATH）、文件名（NAME）、文件扩展名（EXT）、不带扩展名的文件名（NAME_WE）或不带符号链接的完整绝对（ABSOLUTE）文件名。请注意，路径已转换为Unix斜杠格式，并且没有尾随斜杠。始终考虑最长的文件扩展名。如果指定了可选的CACHE参数，则结果变量将添加到缓存中。

      get_filename_component(VarName FileName
                             PROGRAM [PROGRAM_ARGS ArgVar]
                             [CACHE])

    系统搜索路径中将找到FileName中的程序，或者将其保留为完整路径。如果PROGRAM_ARGS与PROGRAM一起出现，则FileName字符串中存在的任何命令行参数都将从程序名称中拆分并存储在ArgVar中。这用于从命令行字符串中的程序名称中分离其参数。

  • get_property: 获取属性。
      get_property(<variable>
                   <GLOBAL             |
                    DIRECTORY [dir]    |
                    TARGET    <target> |
                    SOURCE    <source> |
                    TEST      <test>   |
                    VARIABLE>
                   PROPERTY <name>
                   [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])

    从范围内的某个对象获取一个属性。第一个参数指定存储结果的变量。第二个参数确定获取属性的范围。它必须是以下之一

    GLOBAL范围是唯一的，并且不接受名称。

    DIRECTORY范围默认为当前目录，但另一个目录（已由CMake处理）可以通过完整路径或相对路径命名。

    TARGET范围必须命名一个现有的目标。

    SOURCE范围必须命名一个源文件。

    TEST范围必须命名一个现有的测试。

    VARIABLE范围是唯一的，并且不接受名称。

    必需的PROPERTY选项紧跟要获取的属性的名称。如果未设置属性，则返回空值。如果给出了SET选项，则变量将设置为一个布尔值，指示属性是否已设置。如果给出了DEFINED选项，则变量将设置为一个布尔值，指示属性是否已定义，例如使用define_property。如果给出了BRIEF_DOCS或FULL_DOCS，则变量将设置为一个包含请求属性文档的字符串。如果请求未定义属性的文档，则返回NOTFOUND。

  • if: 有条件地执行一组命令。
      if(expression)
        # then section.
        COMMAND1(ARGS ...)
        COMMAND2(ARGS ...)
        ...
      elseif(expression2)
        # elseif section.
        COMMAND1(ARGS ...)
        COMMAND2(ARGS ...)
        ...
      else(expression)
        # else section.
        COMMAND1(ARGS ...)
        COMMAND2(ARGS ...)
        ...
      endif(expression)

    评估给定的表达式。如果结果为真，则调用THEN部分中的命令。否则，将调用else部分中的命令。elseif和else部分是可选的。您可以有多个elseif子句。请注意，必须为if和endif提供相同的表达式。可以使用长表达式，优先级顺序是首先评估EXISTS、COMMAND和DEFINED运算符。然后评估任何EQUAL、LESS、GREATER、STRLESS、STRGREATER、STREQUAL、MATCHES。然后评估NOT运算符，最后评估AND、OR运算符。可能的表达式为

      if(variable)

    如果变量的值不为空、0、N、NO、OFF、FALSE、NOTFOUND或<variable>-NOTFOUND，则为真。

      if(NOT variable)

    如果变量的值为空、0、N、NO、OFF、FALSE、NOTFOUND或<variable>-NOTFOUND，则为真。

      if(variable1 AND variable2)

    如果两个变量都分别被认为是真，则为真。

      if(variable1 OR variable2)

    如果任一变量分别被认为是真，则为真。

      if(COMMAND command-name)

    如果给定的名称是可以调用的命令、宏或函数，则为真。

      if(POLICY policy-id)

    如果给定的名称是现有的策略（格式为CMP<NNNN>），则为真。

      if(TARGET target-name)

    如果给定的名称是现有的目标（已构建或导入），则为真。

      if(EXISTS file-name)
      if(EXISTS directory-name)

    如果给定的文件或目录存在，则为真。仅对于完整路径，行为才定义明确。

      if(file1 IS_NEWER_THAN file2)

    如果file1比file2新，或者两个文件之一不存在，则为真。仅对于完整路径，行为才定义明确。

      if(IS_DIRECTORY directory-name)

    如果给定的名称是目录，则为真。仅对于完整路径，行为才定义明确。

      if(IS_ABSOLUTE path)

    如果给定的路径是绝对路径，则为真。

       if(variable MATCHES regex)
      if(string MATCHES regex)

    如果给定的字符串或变量的值与给定的正则表达式匹配，则为真。

      if(variable LESS number)
      if(string LESS number)
      if(variable GREATER number)
      if(string GREATER number)
      if(variable EQUAL number)
      if(string EQUAL number)

    如果给定的字符串或变量的值是有效的数字，并且不等式或等式为真，则为真。

      if(variable STRLESS string)
      if(string STRLESS string)
      if(variable STRGREATER string)
      if(string STRGREATER string)
      if(variable STREQUAL string)
      if(string STREQUAL string)

    如果给定的字符串或变量的值在字典上小于（或大于、或等于）右侧的字符串，则为真。

      if(version1 VERSION_LESS version2)
      if(version1 VERSION_EQUAL version2)
      if(version1 VERSION_GREATER version2)

    分量级整数版本号比较（版本格式为major[.minor[.patch[.tweak]]]）。

      if(DEFINED variable)

    如果给定的变量已定义，则为真。变量是真还是假都没有关系，只要它已设置即可。

  • include: 从给定的文件读取CMake列表文件代码。
      include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
                            [NO_POLICY_SCOPE])

    从给定的文件读取CMake列表文件代码。文件中的命令会立即被处理，就像它们被写入include命令的位置一样。如果存在OPTIONAL，则如果文件不存在，则不会引发错误。如果给出了RESULT_VARIABLE，则变量将设置为已包含的完整文件名，如果失败则为NOTFOUND。

    如果指定了模块而不是文件，则会在CMAKE_MODULE_PATH中搜索名为<modulename>.cmake的文件。

    有关 NO_POLICY_SCOPE 选项的讨论，请参阅 cmake_policy() 命令文档。

  • list: 列表操作。
      list(LENGTH <list> <output variable>)
      list(GET <list> <element index> [<element index> ...] <output variable>)
      list(APPEND <list> <element> [<element> ...])
      list(FIND <list> <value> <output variable>)
      list(INSERT <list> <element_index> <element> [<element> ...])
      list(REMOVE_ITEM <list> <value> [<value> ...])
      list(REMOVE_AT <list> <index> [<index> ...])
      list(REMOVE_DUPLICATES <list>)
      list(REVERSE <list>)
      list(SORT <list>)

    LENGTH将返回给定列表的长度。

    GET将返回列表中由索引指定的元素列表。

    APPEND将元素附加到列表中。

    FIND将返回列表中指定元素的索引，如果未找到则返回-1。

    INSERT将元素插入到列表的指定位置。


    REMOVE_AT 和 REMOVE_ITEM 会从列表中删除项目。区别在于 REMOVE_ITEM 会删除给定的项目，而 REMOVE_AT 会删除给定索引处的项目。

    REMOVE_DUPLICATES 会删除列表中重复的项目。

    REVERSE 会就地反转列表的内容。

    SORT 会按字母顺序就地排序列表。

    注意：CMake 中的列表是由分号分隔的一组字符串。可以使用 set 命令创建列表。例如，set(var a b c d e) 创建一个包含 a;b;c;d;e 的列表，而 set(var "a b c d e") 创建一个字符串或包含一个项目的列表。

    指定索引值时，如果 <元素索引> 为 0 或更大，则从列表开头开始索引，其中 0 表示第一个列表元素。如果 <元素索引> 为 -1 或更小，则从列表末尾开始索引，其中 -1 表示最后一个列表元素。使用负索引计数时要小心：它们不是从 0 开始的。-0 等价于 0，即第一个列表元素。

  • macro：开始录制宏以便稍后作为命令调用。
      macro(<name> [arg1 [arg2 [arg3 ...]]])
        COMMAND1(ARGS ...)
        COMMAND2(ARGS ...)
        ...
      endmacro(<name>)

    定义一个名为 <name> 的宏，该宏接受名为 arg1 arg2 arg3 (...) 的参数。在宏之后但在匹配的 endmacro 之前列出的命令在调用宏之前不会被调用。当它被调用时，宏中记录的命令首先通过用传递的参数替换形式参数 (${arg1}) 来修改，然后像普通命令一样调用。除了引用形式参数外，还可以引用值 ${ARGC}，它将设置为传递给函数的参数数量，以及 ${ARGV0} ${ARGV1} ${ARGV2} ...，它们将具有传递的参数的实际值。这有助于创建具有可选参数的宏。此外，${ARGV} 包含传递给宏的所有参数的列表，${ARGN} 包含传递给最后一个预期参数后的参数列表。请注意，宏的参数和 ARGN 等值在通常的 CMake 意义上不是变量。它们是字符串替换，就像 c 预处理器对宏所做的那样。如果您需要真正的 CMake 变量，您应该查看 function 命令。

    有关宏内部策略的行为，请参阅 cmake_policy() 命令文档。

  • make_directory：已弃用。请改用 file(MAKE_DIRECTORY ) 命令。
      make_directory(directory)

    创建指定的目录。应提供完整路径。任何不存在的父目录也将被创建。谨慎使用。

  • mark_as_advanced：将 CMake 缓存变量标记为高级变量。
      mark_as_advanced([CLEAR|FORCE] VAR VAR2 VAR...)

    将命名的缓存变量标记为高级变量。除非启用了显示高级选项，否则高级变量不会在任何 CMake GUI 中显示。如果 CLEAR 是第一个参数，则高级变量将更改回非高级变量。如果 FORCE 是第一个参数，则变量将被设为高级变量。如果既未指定 FORCE 也未指定 CLEAR，则新值将被标记为高级变量，但如果变量已经具有高级/非高级状态，则不会更改。

    它在脚本模式下不执行任何操作。

  • math：数学表达式。
      math(EXPR <output variable> <math expression>)

    EXPR 计算数学表达式并在输出变量中返回结果。示例数学表达式为 '5 * ( 10 + 13 )'。支持的操作符有 + - * / % | & ^ ~ << >> * / %。它们与在 c 代码中的含义相同。

  • message：向用户显示消息。
      message([SEND_ERROR | STATUS | FATAL_ERROR]
              "message to display" ...)

    默认情况下，消息显示在弹出窗口（CMakeSetup）中，或在 cmake 的标准输出中，或 ccmake 的错误部分中。如果第一个参数是 SEND_ERROR，则会引发错误，并且生成阶段将被跳过。如果第一个参数是 FATAL_ERROR，则所有处理都将停止。如果第一个参数是 STATUS，则消息将在 GUI 的进度行中显示，或在命令行 cmake 中用 -- 显示。

  • option：提供用户可以选择的一个选项。
      option(<option_variable> "help string describing option"
             [initial value])

    提供一个选项供用户选择 ON 或 OFF。如果未提供初始值，则使用 OFF。

  • remove：已弃用。请改用 list(REMOVE_ITEM ) 命令。
      remove(VAR VALUE VALUE ...)

    从变量 VAR 中删除 VALUE。这通常用于从向量（例如分号分隔的列表）中删除条目。VALUE 会被展开。

  • return：从文件、目录或函数返回。
      return()

    从文件、目录或函数返回。当在包含的文件（通过 include() 或 find_package()）中遇到此命令时，它会导致当前文件的处理停止，并将控制权返回给包含文件。如果在未被其他文件包含的文件（例如 CMakeLists.txt）中遇到它，则如果存在父目录，则控制权将返回到父目录。如果在函数中调用 return，则控制权将返回到函数的调用方。请注意，宏不是函数，并且不会像函数那样处理 return。

  • separate_arguments：将空格分隔的参数拆分为分号分隔的列表。
      separate_arguments(VARIABLE)

    将 VARIABLE 的值转换为分号分隔的列表。所有空格都将替换为';'。这有助于生成命令行。

  • set：将 CMAKE 变量设置为给定值。
      set(<variable> <value> [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])

    在 CMake 中，将 <variable> 设置为值 <value>。在 <variable> 设置为 <value> 之前，<value> 会被展开。如果存在 CACHE，则 <variable> 会被放入缓存。然后需要 <type> 和 <docstring>。<type> 由 CMake GUI 用于选择用户设置值的窗口小部件。<type> 的值可以是

      FILEPATH = File chooser dialog.
      PATH     = Directory chooser dialog.
      STRING   = Arbitrary string.
      BOOL     = Boolean ON/OFF checkbox.
      INTERNAL = No GUI entry (used for persistent variables).

    如果 <type> 是 INTERNAL，则 <value> 始终写入缓存，替换缓存中存在的任何值。如果它不是缓存变量，则这始终写入当前 makefile。FORCE 选项将覆盖缓存值，删除用户所做的任何更改。

    如果存在 PARENT_SCOPE，则变量将在当前作用域的上方作用域中设置。每个新目录或函数都会创建一个新作用域。此命令会将变量的值设置为父目录或调用函数（取决于具体情况）。如果未指定 VALUE，则变量将从父作用域中删除。

      set(<variable> <value1> ... <valueN>)

    在这种情况下，<variable> 被设置为一个由分号分隔的值列表。

    <variable> 可以是环境变量，例如

      set( ENV{PATH} /home/martink )

    在这种情况下，将设置环境变量。

  • set_directory_properties：设置目录的属性。
      set_directory_properties(PROPERTIES prop1 value1 prop2 value2)

    为当前目录及其子目录设置属性。如果找不到该属性，CMake 将报告错误。这些属性包括：INCLUDE_DIRECTORIES、LINK_DIRECTORIES、INCLUDE_REGULAR_EXPRESSION 和 ADDITIONAL_MAKE_CLEAN_FILES。

    ADDITIONAL_MAKE_CLEAN_FILES 是一个文件列表，这些文件将在“make clean”阶段作为一部分被清理。

  • set_property：在给定作用域中设置命名属性。
      set_property(<GLOBAL                            |
                    DIRECTORY [dir]                   |
                    TARGET    [target1 [target2 ...]] |
                    SOURCE    [src1 [src2 ...]]       |
                    TEST      [test1 [test2 ...]]>
                   [APPEND]
                   PROPERTY <name> [value1 [value2 ...]])

    在一个或多个给定作用域的对象上设置一个属性。第一个参数确定设置属性的作用域。它必须是以下之一

    GLOBAL范围是唯一的，并且不接受名称。

    DIRECTORY范围默认为当前目录，但另一个目录（已由CMake处理）可以通过完整路径或相对路径命名。

    TARGET 作用域可以命名零个或多个现有目标。

    SOURCE 作用域可以命名零个或多个源文件。

    TEST 作用域可以命名零个或多个现有测试。

    必需的 PROPERTY 选项紧跟要设置的属性名称。其余参数用于以分号分隔列表的形式组合属性值。如果给出了 APPEND 选项，则该列表将附加到任何现有的属性值。

  • site_name：将给定变量设置为计算机的名称。
      site_name(variable)
  • string：字符串操作。
      string(REGEX MATCH <regular_expression>
             <output variable> <input> [<input>...])
      string(REGEX MATCHALL <regular_expression>
             <output variable> <input> [<input>...])
      string(REGEX REPLACE <regular_expression>
             <replace_expression> <output variable>
             <input> [<input>...])
      string(REPLACE <match_string>
             <replace_string> <output variable>
             <input> [<input>...])
      string(COMPARE EQUAL <string1> <string2> <output variable>)
      string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
      string(COMPARE LESS <string1> <string2> <output variable>)
      string(COMPARE GREATER <string1> <string2> <output variable>)
      string(ASCII <number> [<number> ...] <output variable>)
      string(CONFIGURE <string1> <output variable>
             [@ONLY] [ESCAPE_QUOTES])
      string(TOUPPER <string1> <output variable>)
      string(TOLOWER <string1> <output variable>)
      string(LENGTH <string> <output variable>)
      string(SUBSTRING <string> <begin> <length> <output variable>)
      string(STRIP <string> <output variable>)
      string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
             <output variable>)

    REGEX MATCH 将匹配正则表达式一次并将匹配项存储在输出变量中。

    REGEX MATCHALL 将尽可能多次匹配正则表达式并将匹配项作为列表存储在输出变量中。

    REGEX REPLACE 将尽可能多次匹配正则表达式并用替换表达式替换匹配项。替换表达式可以使用 \1、\2、...、\9 引用匹配项的括号分隔的子表达式。请注意，在 CMake 代码中需要两个反斜杠 (\\1) 才能使反斜杠通过参数解析。

    REPLACE 将用 replace_string 替换输入中所有出现的 match_string 并将结果存储在输出中。

    COMPARE EQUAL/NOTEQUAL/LESS/GREATER 将比较字符串并将 true 或 false 存储在输出变量中。

    ASCII 将所有数字转换为相应的 ASCII 字符。

    CONFIGURE 将转换字符串，就像 CONFIGURE_FILE 转换文件一样。

    TOUPPER/TOLOWER 将字符串转换为大写/小写字符。

    LENGTH 将返回给定字符串的长度。

    SUBSTRING 将返回给定字符串的子字符串。

    STRIP 将返回给定字符串的子字符串，并删除前导和尾随空格。

    RANDOM 将返回一个给定长度的随机字符串，该字符串由给定字母表中的字符组成。默认长度为 5 个字符，默认字母表为所有数字以及大写和小写字母。

    以下字符在正则表达式中具有特殊含义

       ^         Matches at beginning of a line
       $         Matches at end of a line
       .         Matches any single character
       [ ]       Matches any character(s) inside the brackets
       [^ ]      Matches any character(s) not inside the brackets
        -        Matches any character in range on either side of a dash
       *         Matches preceding pattern zero or more times
       +         Matches preceding pattern one or more times
       ?         Matches preceding pattern zero or once only
       |         Matches a pattern on either side of the |
       ()        Saves a matched subexpression, which can be referenced in the REGEX REPLACE operation. Additionally it is saved in the special CMake variables CMAKE_MATCH_(0..9).
  • unset：取消设置变量、缓存变量或环境变量。
      unset(<variable> [CACHE])

    删除指定的变量，使其变得未定义。如果存在 CACHE，则从缓存而不是当前作用域中删除变量。

    <variable> 可以是环境变量，例如

      unset(ENV{LD_LIBRARY_PATH})

    在这种情况下，将从当前环境中删除变量。

  • variable_watch：监视 CMake 变量的更改。
      variable_watch(<variable name> [<command to execute>])

    如果指定的变量发生更改，则会打印有关变量已更改的消息。如果指定了命令，则会执行该命令。该命令将接收以下参数：COMMAND(<variable> <access> <value> <current list file> <stack>)

  • while：在条件为真时计算一组命令
      while(condition)
        COMMAND1(ARGS ...)
        COMMAND2(ARGS ...)
        ...
      endwhile(condition)

    在 while 和匹配的 endwhile 之间的所有命令都会被记录，而不会被调用。一旦计算了 endwhile，只要条件为真，就会调用记录的命令列表。使用与 if 命令相同的逻辑计算条件。

  • write_file：已弃用。请改用 file(WRITE ) 命令。
      write_file(filename "message to write"... [APPEND])

    第一个参数是文件名，其余参数是要写入的消息。如果指定了参数 APPEND，则消息将被追加。


    注释 1：file(WRITE ... 和 file(APPEND ... 的功能与这个命令完全相同，但增加了其他功能。

    注释 2：使用 write_file 生成的文件不能作为 CMake 的输入（CONFIGURE_FILE、源文件...），因为这会导致无限循环。如果要生成 CMake 的输入文件，请使用 configure_file。

属性

  CMake Properties - Properties supported by CMake, the Cross-Platform Makefile Generator.

本文档介绍了 CMake 支持的属性。属性可以具有不同的作用域。它们可以分配给源文件、目录、目标或全局 CMake。通过修改属性值，可以自定义构建系统的行为。

兼容性命令

  CMake Compatibility Listfile Commands - Obsolete commands supported by CMake for compatibility.

本文档介绍了之前 CMake 版本中现已过时的 listfile 命令，出于兼容性原因，这些命令仍受支持。您应该改用更新、更快、更棒的新命令。;-)

标准 CMake 模块

版权

版权所有 (c) 2002 Kitware, Inc., Insight Consortium。保留所有权利。

在满足以下条件的情况下，允许以源代码和二进制形式重新分发和使用，无论是否修改。

源代码的再分发必须保留上述版权声明、此条件列表和以下免责声明。

二进制形式的再分发必须在随分发提供的文档和/或其他材料中复制上述版权声明、此条件列表和以下免责声明。

未经事先明确的书面许可，不得使用 Kitware, Inc.、Insight Consortium 或任何联盟成员或任何贡献者的名称来认可或推广源自此软件的产品。

修改后的源代码版本必须明确标记为修改版本，并且不得歪曲为原始软件。

本软件由版权所有者和贡献者“按原样”提供，任何明示或暗示的保证，包括但不限于适销性和特定用途适用性的暗示保证，均不作任何保证。在任何情况下，作者或贡献者均不对任何直接、间接、附带、特殊、惩罚性或后果性损害（包括但不限于替代商品或服务的采购；使用、数据或利润损失；或业务中断）负责，无论这些损害是基于任何责任理论造成的，无论是合同、严格责任还是侵权行为（包括疏忽或其他原因），即使已告知可能发生此类损害。

另请参阅

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

有用链接摘要

  Home: http://www.cmake.org
  Docs: http://www.cmake.org/HTML/Documentation.html
  Mail: http://www.cmake.org/HTML/MailingLists.html
  FAQ:  http://www.cmake.org/Wiki/CMake_FAQ