速记签名是:
find_path ( name1 [path1 path2 ...])一般签名是:
find_path ( 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] )此命令用于查找 directory containing the named file。如果指定了 NO_CACHE,则创建缓存条目或普通变量,命名为```` 以存储此命令的结果。如果 |SEARCH_XXX|找到结果存储在变量中,除非清除变量,否则不会重复搜索。如果什么都没有找到,结果将是``-NOTFOUND``。
选项包括:
名字为 file in a directory 指定一个或多个可能的名称。
当使用它来指定带有和不带版本后缀的名称时,我们建议首先指定未版本化的名称,以便可以在分发提供的包之前找到本地构建的包。
提示,路径除默认位置外,还指定要搜索的目录。 ENV var 子选项从系统环境变量中读取路径。
在 3.24 版本发生变更: 在 Windows 平台上,可以使用专用语法 ` 将注册表查询作为目录的一部分包含在内。此类规范将在所有其他平台上被忽略。
REGISTRY_VIEW在 3.24 版本加入.
指定必须查询哪些注册表视图。此选项仅在 Windows 平台上有意义,在其他平台上将被忽略。未指定时,|FIND_XXX_REGISTRY_VIEW_DEFAULT|当 CMP0134 策略为``NEW`` 时使用视图。策略为“旧”时的默认视图,请参阅:policy:CMP0134。
64查询 64 位注册表。在 32 位 Windows 上,它总是返回字符串“/REGISTRY-NOTFOUND”。
32查询 32 位注册表。
64_32查询两个视图(64 和``32``)并为每个视图生成一个路径。
32_64查询两个视图(32 和 64)并为每个视图生成一个路径。
主机查询与主机架构相匹配的注册表:64 位 Windows 上为“64”,32 位 Windows 上为“32”。
目标查询与 CMAKE_SIZEOF_VOID_P 变量指定的体系结构相匹配的注册表。如果未定义,则返回到 HOST 视图。
两者查询两个视图(32 和 64)。顺序取决于以下规则:如果定义了 CMAKE_SIZEOF_VOID_P 变量,则根据此变量的内容使用以下视图:
8:64_32
4:32_64
如果未定义 CMAKE_SIZEOF_VOID_P 变量,则依赖主机的体系结构:
64 位:64_32
32 位:32
PATH_SUFFIXES在每个目录位置下方指定额外的子目录以检查,否则将被考虑。
验证器在 3.25 版本加入.
为找到的每个候选项指定要调用的 function`(无法提供 :command:`macro(),这将导致错误)。两个参数将传递给验证器函数:结果变量的名称和候选项的绝对路径。该项目将被接受并且搜索将结束,除非该函数在调用范围内将结果变量中的值设置为 false。当输入验证器函数时,结果变量将保存一个真值。
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”。缓存的结果不需要通过验证功能。
文档为 缓存条目指定文档字符串。
NO_CACHE在 3.21 版本加入.
搜索结果将存储在一个普通变量中,而不是缓存条目中。
备注
如果变量在调用之前已经设置(作为普通变量或缓存变量),则不会进行搜索。
警告
应谨慎使用此选项,因为它会大大增加重复配置步骤的成本。
需要在 3.18 版本加入.
如果未找到任何内容,则停止处理并显示错误消息,否则下次将再次尝试搜索 |FIND_XXX|使用相同的变量调用。
如果指定了 NO_DEFAULT_PATH,则不会将其他路径添加到搜索中。如果不指定``NO_DEFAULT_PATH``,搜索过程如下:
在 3.12 版本加入: 如果从查找模块或通过调用 find_package()` 加载的任何其他脚本中调用,搜索前缀对于当前找到的包是唯一的。具体来说,查看 _ROOT CMake 变量和 _ROOT 环境变量。包根变量作为堆栈维护,因此如果从嵌套的查找模块或配置包中调用,将在当前模块或包的路径之后搜索父查找模块或配置包的根路径。换句话说,搜索顺序是``_ROOT``、ENV{_ROOT}、_ROOT、ENV{_ROOT}``等。如果传递了 ``NO_PACKAGE_ROOT_PATH 或通过将 CMAKE_FIND_USE_PACKAGE_ROOT_PATH 设置为 FALSE,则可以跳过此步骤。请参阅政策:policy:CMP0074。
/include/ if CMAKE_LIBRARY_ARCHITECTUREis set, and /include for each in the_ROOT CMake variable and the_ROOT environment variable ifcalled from within a find module loaded byfind_package()
在特定于 cmake 的缓存变量中指定的搜索路径。这些旨在与“-DVAR=value”一起在命令行上使用。这些值被解释为:ref:分号分隔的列表 。如果传递了 NO_CMAKE_PATH 或通过将 CMAKE_FIND_USE_CMAKE_PATH 设置为 FALSE 可以跳过这一步。
/include/ if CMAKE_LIBRARY_ARCHITECTUREis set, and /include for each in CMAKE_PREFIX_PATH
CMAKE_INCLUDE_PATH
CMAKE_FRAMEWORK_PATH
在特定于 cmake 的环境变量中指定的搜索路径。这些旨在在用户的 shell 配置中设置,因此使用主机的本机路径分隔符(Windows 上为“;”,UNIX 上为“ :”)。如果传递了 NO_CMAKE_ENVIRONMENT_PATH 或通过将 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH 设置为 FALSE 可以跳过这一步。
/include/ if CMAKE_LIBRARY_ARCHITECTUREis set, and /include for each in CMAKE_PREFIX_PATH
CMAKE_INCLUDE_PATH
CMAKE_FRAMEWORK_PATH
搜索由“HINTS”选项指定的路径。这些应该是系统自省计算出的路径,例如由已找到的另一个项目的位置提供的提示。硬编码的猜测应该用 PATHS 选项指定。
搜索标准系统环境变量。如果传递了 NO_SYSTEM_ENVIRONMENT_PATH 或通过将 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH 设置为 FALSE 可以跳过这一步。
The directories in INCLUDEand PATH.
On Windows hosts:/include/ if CMAKE_LIBRARY_ARCHITECTUREis set, and /include for each /[s]bin in PATH, and/include for other entries in 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,则可以跳过所有这些位置。
/include/ if CMAKE_LIBRARY_ARCHITECTUREis set, and /include for each inCMAKE_SYSTEM_PREFIX_PATH
CMAKE_SYSTEM_INCLUDE_PATH
CMAKE_SYSTEM_FRAMEWORK_PATH
这些变量包含的平台路径是通常包含已安装软件的位置。一个例子是 /usr/local 用于基于 UNIX 的平台。
搜索由 PATHS 选项或命令的简写版本指定的路径。这些通常是硬编码的猜测。
CMAKE_IGNORE_PATH、CMAKE_IGNORE_PREFIX_PATH、CMAKE_SYSTEM_IGNORE_PATH 和 CMAKE_SYSTEM_IGNORE_PREFIX_PATH 变量也可能导致上述某些位置被忽略。
在 3.16 版本加入: 添加了 CMAKE_FIND_USE__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 也有其他影响。有关