find_program¶

简写签名是

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

常规签名是

find_program (
          <VAR>
          name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
          [HINTS [path | ENV var]... ]
          [PATHS [path | ENV var]... ]
          [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [VALIDATOR function]
          [DOC "cache documentation string"]
          [NO_CACHE]
          [REQUIRED]
          [NO_DEFAULT_PATH]
          [NO_PACKAGE_ROOT_PATH]
          [NO_CMAKE_PATH]
          [NO_CMAKE_ENVIRONMENT_PATH]
          [NO_SYSTEM_ENVIRONMENT_PATH]
          [NO_CMAKE_SYSTEM_PATH]
          [NO_CMAKE_INSTALL_PREFIX]
          [CMAKE_FIND_ROOT_PATH_BOTH |
           ONLY_CMAKE_FIND_ROOT_PATH |
           NO_CMAKE_FIND_ROOT_PATH]
         )

此命令用于查找程序。如果指定 NO_CACHE，则根据 <VAR> 命名存储此命令结果的缓存条目或常规变量。如果找到该程序，则将结果存储在变量中，除非清除该变量，否则不重复搜索。如果未找到任何内容，则结果将为 <VAR>-NOTFOUND。

选项包括

NAMES

指定程序的一个或多个可能名称。

当使用此命令指定带有或不带有版本后缀的名称时，我们建议先指定未添加版本的名称，以便在本地构建的包可以先于分发提供的包被找到。

HINTS、PATHS

指定要在除了默认位置之外进行搜索的目录。 ENV var 子选项会从系统环境变量中读取路径。

版本 3.24 中已更改：在 Windows 平台上，可以使用特定语法将注册表查询作为目录的一部分。此类规范将在所有其他平台上被忽略。

REGISTRY_VIEW

在版本 3.24 中添加。

指定必须查询的注册表视图。此选项仅在 Windows 平台上才有意义，且将在其他平台上被忽略。未指定时，当 CMP0134 策略为 NEW 时，将使用 BOTH 视图。当该策略为 OLD 时，请参阅 CMP0134 以了解默认视图。

64

查询 64 位注册表。在 32 位 Windows 上，它始终返回字符串 /REGISTRY-NOTFOUND。

32

查询 32 位注册表。

64_32

查询两个视图（64 和 32），并为每个视图生成路径。

32_64

查询两个视图（32 和 64），并为每个视图生成路径。

HOST

查询匹配主机架构的注册表：在 64 位 Windows 上为 64，在 32 位 Windows 上为 32。

TARGET

查询与 CMAKE_SIZEOF_VOID_P 变量指定的架构匹配的注册表。如果未定义，则回退到 HOST 视图。

BOTH

查询两个视图（32 和 64）。顺序取决于以下规则：如果 CMAKE_SIZEOF_VOID_P 变量已定义，则根据此变量的内容使用以下视图

8: 64_32
4: 32_64

如果 CMAKE_SIZEOF_VOID_P 变量未定义，则依赖于主机的架构

64 位：64_32
32 位：32

PATH_SUFFIXES

指定其他子目录在已被视为正常目录位置的子目录进行检查。

VALIDATOR

版本 3.25 中添加。

指定一个要对找到的每个候选项调用的 function()（不能提供 macro()，会导致一个错误）。两个参数将传递给验证程序函数：结果变量的名称及其绝对路径到候选项。该项会被接受，并且搜索将会结束，除非该函数将结果变量的值在调用作用域中设置成 false。当进入验证程序函数时，结果变量将保存一个 true 值。

function(my_check validator_result_var item)
  if(NOT item MATCHES ...)
    set(${validator_result_var} FALSE PARENT_SCOPE)
  endif()
endfunction()

find_program (result NAMES ... VALIDATOR my_check)

请注意，如果使用的是已缓存结果，则搜索将被跳过，任何 VALIDATOR 都将被忽略。已缓存结果没有必要通过验证函数。

DOC

为 <VAR> 缓存条目指定文档字符串。

NO_CACHE

版本 3.21 中添加。

搜索值将存储在一个 normal 变量中，而不是一个缓存条目中。

请注意

如果变量在调用之前已经设置（作为 normal 变量或缓存变量），则搜索将不会发生。

警告

这个选项应谨慎使用，因为它会大大增加重复配置步骤的成本。

REQUIRED

版本 3.18 中添加。

如果没有任何发现，停止执行并显示一条错误信息，否则下一此使用同一变量调用 find_program 时，搜索将会再次尝试。

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

如果从一个查找模块或其他通过调用 find_package(<PackageName>) 加载的脚本中调用，则搜索在当前正在查找的包中唯一的搜索前缀。参见策略 CMP0074。

在版本 3.12 中添加。

具体而言，按顺序搜索以下变量指定搜索的路径
1. <PackageName>_ROOT CMake 变量，其中 <PackageName> 是保留大小写的包名。
2. <PACKAGENAME>_ROOT CMake 变量，其中 <PACKAGENAME> 是大写的包名。参见策略 CMP0144。
  
  在版本 3.27 中添加。
3. <PackageName>_ROOT 环境变量，其中 <PackageName> 是保留大小写的包名。
4. <PACKAGENAME>_ROOT 环境变量，其中 <PACKAGENAME> 是大写的包名。参见策略 CMP0144。
  
  在版本 3.27 中添加。
包根变量会被当做栈来维护，所以如果从嵌套的查找模块或者配置包中调用，则从父查找模块或配置包中跟路径将在当前模块或包的路径后被搜索。换句话说，搜索顺序应该是 <CurrentPackage>_ROOT，ENV{<CurrentPackage>_ROOT}，<ParentPackage>_ROOT，ENV{<ParentPackage>_ROOT}，以此类推。如果 NO_PACKAGE_ROOT_PATH 已传递或通过将 CMAKE_FIND_USE_PACKAGE_ROOT_PATH 设置为 FALSE，则可以跳过。
- <prefix>/[s]bin 对于 <PackageName>_ROOT CMake 变量中的每个 <prefix> 以及在通过由 find_package(<PackageName>) 加载的 find 模块内部调用时 <PackageName>_ROOT 环境变量
由特定的 CMake 缓存变量指定搜索路径。这些变量的目标是在命令行中使用 -DVAR=value。这些值被解释为以分号分隔的列表。如果传递 NO_CMAKE_PATH 或将 CMAKE_FIND_USE_CMAKE_PATH 设置为 FALSE，则可以跳过它。
- <prefix>/[s]bin 对于 CMAKE_PREFIX_PATH 中的每个 <prefix>
- CMAKE_PROGRAM_PATH
- CMAKE_APPBUNDLE_PATH
由特定的 CMake 环境变量指定搜索路径。这些变量的目标是在用户的 shell 配置中设置，因此使用主机的本机路径分隔符（在 Windows 上为 ;，在 UNIX 上为 :）。如果传递 NO_CMAKE_ENVIRONMENT_PATH 或将 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH 设置为 FALSE，则可以跳过它。
- <prefix>/[s]bin 对于 CMAKE_PREFIX_PATH 中的每个 <prefix>
- CMAKE_PROGRAM_PATH
- CMAKE_APPBUNDLE_PATH
搜索由 HINTS 选项指定的路径。这些路径应该由系统自省计算得出，比如另一个已找到的项位置提供的提示。硬编码的猜测应该用 PATHS 选项指定。
搜索标准系统环境变量。如果传递了 NO_SYSTEM_ENVIRONMENT_PATH 或将 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH 设为 FALSE，即可以跳过此步骤。
- PATH 本身的目录。
搜索在当前系统平台文件中定义的 cmake 变量。如果传递了 NO_CMAKE_INSTALL_PREFIX 或将 CMAKE_FIND_USE_INSTALL_PREFIX 设为 FALSE，搜索 CMAKE_INSTALL_PREFIX 和 CMAKE_STAGING_PREFIX 时即可以跳过此步骤。如果传递了 NO_CMAKE_SYSTEM_PATH 或将 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH 设为 FALSE，即可跳过所有这些位置。
- 对于 CMAKE_SYSTEM_PREFIX_PATH 中的每一个 <prefix>，使用以下值：
- CMAKE_SYSTEM_PROGRAM_PATH
- CMAKE_SYSTEM_APPBUNDLE_PATH
这些变量包含的平台路径是一些通常包含已安装软件的位置。例如，对于基于 UNIX 的平台，使用 /usr/local。
搜索由 PATHS 选项指定或在命令简写中提供的路径。这些路径通常是硬编码的猜测。

变量 CMAKE_IGNORE_PATH、CMAKE_IGNORE_PREFIX_PATH、CMAKE_SYSTEM_IGNORE_PATH 和 CMAKE_SYSTEM_IGNORE_PREFIX_PATH 还可能导致以上某些位置被忽略。

3.16 版本中新增：添加 CMAKE_FIND_USE_<CATEGORY>_PATH 变量，全局禁用各种搜索位置。

在 macOS 上，变量 CMAKE_FIND_FRAMEWORK 和 CMAKE_FIND_APPBUNDLE 确定 Apple 风格和 unix 风格包组件之间的首选顺序。

CMake 变量 CMAKE_FIND_ROOT_PATH 指定一个或多个目录，将其前置于所有其他搜索目录之前。这有效地将整个搜索“重新扎根”在给定位置下。派生自 CMAKE_STAGING_PREFIX 的路径从这种重新扎根中被排除，因为该变量始终是主机系统上的一个路径。默认情况下，CMAKE_FIND_ROOT_PATH 为空。

变量 CMAKE_SYSROOT 也可用于指定确切的一个用作前缀的目录。设置 CMAKE_SYSROOT 还会有其他影响。有关更多信息，请参阅该变量的文档。

这些变量在交叉编译时特别有用，可以指向目标环境的根目录，并且 CMake 将在那里搜索。默认情况下，首先搜索在 CMAKE_FIND_ROOT_PATH 中列出的目录，然后搜索 CMAKE_SYSROOT 目录，最后再搜索非根目录。可以通过设置 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: 仅搜索重新根目录的目录和 CMAKE_STAGING_PREFIX 下的目录。

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

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

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

当向 NAMES 选项提供多个值时，此命令默认一次考虑一个名称，并在每个目录中搜索它。 NAMES_PER_DIR 选项告知此命令一次考虑一个目录，并搜索其中的所有名称。

被视为程序的文件集是特定于平台的

在 Windows 上，按顺序考虑文件名后缀 .com、.exe 和无后缀。
在非 Windows 系统上，不考虑任何文件名后缀，但文件必须具有执行权限（请参见策略 CMP0109）。

要搜索脚本，请明确指定一个扩展名

if(WIN32)
  set(_script_suffix .bat)
else()
  set(_script_suffix .sh)
endif()

find_program(MY_SCRIPT NAMES my_script${_script_suffix})

find_program¶

上一主题

下一主题

本页