find_file¶

简写签名是

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

通用签名是

find_file (
          <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 位 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，否则该项目将被接受，并且搜索将结束。当输入验证器函数时，结果变量将保持真值。

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

find_file (result NAMES ... VALIDATOR my_check)

请注意，如果使用缓存的结果，则会跳过搜索，并且任何 VALIDATOR 都将被忽略。缓存的结果不需要通过验证函数。

DOC

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

NO_CACHE

在 3.21 版本中添加。

搜索结果将存储在普通变量中，而不是缓存条目中。

注意

如果在调用之前已经设置了变量（作为普通变量或缓存变量），则不会进行搜索。

警告

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

REQUIRED

在 3.18 版本中添加。

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

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

如果从 find 模块或通过调用 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 版本中添加。
软件包根变量维护为堆栈，因此如果从嵌套的 find 模块或配置软件包中调用，则将在当前模块或软件包的路径之后搜索父级的 find 模块或配置软件包的根路径。换句话说，搜索顺序将是 <CurrentPackage>_ROOT、ENV{<CurrentPackage>_ROOT}、<ParentPackage>_ROOT、ENV{<ParentPackage>_ROOT} 等。如果传递了 NO_PACKAGE_ROOT_PATH 或将 CMAKE_FIND_USE_PACKAGE_ROOT_PATH 设置为 FALSE，则可以跳过此步骤。
- 如果设置了 CMAKE_LIBRARY_ARCHITECTURE，则为 <prefix>/include/<arch>，以及对于 <PackageName>_ROOT CMake 变量和 <PackageName>_ROOT 环境变量中的每个 <prefix>，如果从 find_package(<PackageName>) 加载的 find 模块中调用，则为 <prefix>/include
cmake 特定缓存变量中指定的搜索路径。这些旨在与 -DVAR=value 一起在命令行上使用。这些值被解释为分号分隔的列表。如果传递了 NO_CMAKE_PATH 或将 CMAKE_FIND_USE_CMAKE_PATH 设置为 FALSE，则可以跳过此步骤。
- 如果设置了 CMAKE_LIBRARY_ARCHITECTURE，则为 <prefix>/include/<arch>，以及对于 CMAKE_PREFIX_PATH 中的每个 <prefix>，则为 <prefix>/include
- CMAKE_INCLUDE_PATH
- CMAKE_FRAMEWORK_PATH
cmake 特定环境变量中指定的搜索路径。这些旨在在用户的 shell 配置中设置，因此使用主机本机路径分隔符（Windows 上为 ;，UNIX 上为 :）。如果传递了 NO_CMAKE_ENVIRONMENT_PATH 或将 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH 设置为 FALSE，则可以跳过此步骤。
- 如果设置了 CMAKE_LIBRARY_ARCHITECTURE，则为 <prefix>/include/<arch>，以及对于 CMAKE_PREFIX_PATH 中的每个 <prefix>，则为 <prefix>/include
- 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 搜索了其他路径：如果设置了 CMAKE_LIBRARY_ARCHITECTURE，则为 <prefix>/include/<arch>，以及对于 PATH 中的每个 <prefix>/[s]bin，则为 <prefix>/include，对于 PATH 中的其他条目，则为 <entry>/include。此行为已在 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，则可以跳过所有这些位置。
- 如果设置了 CMAKE_LIBRARY_ARCHITECTURE，则为 <prefix>/include/<arch>，以及对于 CMAKE_SYSTEM_PREFIX_PATH 中的每个 <prefix>，则为 <prefix>/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 中列出的目录，然后搜索 CMAKE_SYSROOT 目录，然后搜索非根目录。可以通过设置 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_STAGING_PREFIX 下的目录。

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

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

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

find_file¶

上一主题

下一主题

本页