find_path¶

简写签名为

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

常规签名为

find_path (
          <VAR>
          name | NAMES name1 [name2 ...]
          [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 时将使用 TARGET 视图。当该策略为 OLD 时，请参阅 CMP0134 以获取默认视图。

64

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

32

查询 32 位注册表。

64_32

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

32_64

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

HOST

查询与主机架构匹配的注册表：64 位系统上的 64，32 位系统上的 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_path (result NAMES ... VALIDATOR my_check)

请注意，如果使用了缓存结果，则搜索将被跳过并忽略任何 VALIDATOR。要求缓存结果通过验证功能。

DOC

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

NO_CACHE

在版本 3.21 中添加。

搜索结果将存储在正常变量中，而不是缓存项中。

注意

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

警告

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

REQUIRED

在版本 3.18 中添加。

如果未找到任何内容，则停止处理并显示错误消息，否则下一次调用具有相同变量的 find_path 时将再次尝试搜索。

如果指定了 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>/include/<arch> 如果 CMAKE_LIBRARY_ARCHITECTURE 已设置，以及 <prefix>/include 对于每个 <prefix> 在 <PackageName>_ROOT CMake 变量中并 <PackageName>_ROOT 环境变量中，如果由 find_package(<PackageName>) 加载的 find 模块内调用
在 cmake 特定的缓存变量中指定搜索路径。这些变量旨在与 -DVAR=value 一起用于命令行。这些值被解释为分号分隔的列表。如果传递了 NO_CMAKE_PATH 或将 CMAKE_FIND_USE_CMAKE_PATH 设置为 FALSE，可以跳过此项。
- <prefix>/include/<arch> 如果 CMAKE_LIBRARY_ARCHITECTURE 已设置，以及 <prefix>/include 对于 CMAKE_PREFIX_PATH 中的每个 <prefix>
- CMAKE_INCLUDE_PATH
- CMAKE_FRAMEWORK_PATH
在 cmake 特定的环境变量中指定搜索路径。这些路径旨在在用户的 shell 配置中设置，因此会使用主机原生的路径分隔符（Windows 上为 ;，UNIX 上为 :）。如果传递了 NO_CMAKE_ENVIRONMENT_PATH 或将 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH 设置为 FALSE，可以跳过此项。
- <prefix>/include/<arch> 如果CMAKE_LIBRARY_ARCHITECTURE已设置，还有<prefix>/include 对于每个<prefix> 在CMAKE_PREFIX_PATH
- CMAKE_INCLUDE_PATH
- CMAKE_FRAMEWORK_PATH
搜索HINTS选项指定的路径。这些路径应由系统自省计算，例如已找到的另一项位置提供的提示。硬编码猜测应使用PATHS选项指定。
搜索标准系统环境变量。如果传递了NO_SYSTEM_ENVIRONMENT_PATH 或者通过将CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH设置为FALSE可以跳过此操作。
- 目录中的INCLUDE和PATH。
在 Windows 主机上，CMake 3.3 到 3.27 搜索了其他路径：<prefix>/include/<arch> 如果CMAKE_LIBRARY_ARCHITECTURE已设置，还有<prefix>/include 对于每个<prefix>/[s]bin 在PATH中，还有<entry>/include 对于PATH中的其他条目。此行为已由 CMake 3.28 删除。
搜索当前系统平台文件中定义的 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可以跳过所有这些位置。
- <前缀>/include/<arch>，如果 CMAKE_LIBRARY_ARCHITECTURE 已设置，以及 CMAKE_SYSTEM_PREFIX_PATH 中的每个 <前缀> 的 <前缀>/include
- CMAKE_SYSTEM_INCLUDE_PATH
- CMAKE_SYSTEM_FRAMEWORK_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_MODE_INCLUDE 调整默认行为。使用选项可以手动覆盖此行为，依具体调用情况而定

CMAKE_FIND_ROOT_PATH_BOTH: 按照上述顺序进行搜索。
NO_CMAKE_FIND_ROOT_PATH: 不要使用变量。
ONLY_CMAKE_FIND_ROOT_PATH: 仅搜索 CMAKE_STAGING_PREFIX 下的已重新建立根目录和目录。

默认搜索顺序专为最具体到最不具体常见用例而设计。项目可以通过多次调用命令及使用 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_path¶

前一主题

下一主题

本页