查找库

速记签名是：

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

一般签名是：

find_library (
          <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]
         )

此命令用于查找 library。如果指定了 NO_CACHE，则创建缓存条目或普通变量，命名为``<VAR>`` 以存储此命令的结果。如果 |SEARCH_XXX|找到结果存储在变量中，除非清除变量，否则不会重复搜索。如果什么都没有找到，结果将是``<VAR>-NOTFOUND``。

选项包括：

名字

为 library 指定一个或多个可能的名称。

当使用它来指定带有和不带版本后缀的名称时，我们建议首先指定未版本化的名称，以便可以在分发提供的包之前找到本地构建的包。

提示，路径

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

在 3.24 版本发生变更: 在 Windows 平台上，可以使用专用语法 <Find Using Windows Registry>` 将注册表查询作为目录的一部分包含在内。此类规范将在所有其他平台上被忽略。

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_library (result NAMES ... VALIDATOR my_check)

请注意，如果使用缓存结果，则会跳过搜索并忽略任何“VALIDATOR”。缓存的结果不需要通过验证功能。

文档

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

NO_CACHE

在 3.21 版本加入.

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

备注

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

警告

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

需要

在 3.18 版本加入.

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

如果指定了 NO_DEFAULT_PATH，则不会将其他路径添加到搜索中。如果不指定``NO_DEFAULT_PATH``，搜索过程如下：

1. 在 3.12 版本加入: 如果从查找模块或通过调用 find_package(<PackageName>)` 加载的任何其他脚本中调用，搜索前缀对于当前找到的包是唯一的。具体来说，查看 <PackageName>_ROOT CMake 变量和 <PackageName>_ROOT 环境变量。包根变量作为堆栈维护，因此如果从嵌套的查找模块或配置包中调用，将在当前模块或包的路径之后搜索父查找模块或配置包的根路径。换句话说，搜索顺序是``<CurrentPackage>_ROOT``、ENV{<CurrentPackage>_ROOT}、<ParentPackage>_ROOT、ENV{<ParentPackage>_ROOT}``等。如果传递了 ``NO_PACKAGE_ROOT_PATH 或通过将 CMAKE_FIND_USE_PACKAGE_ROOT_PATH 设置为 FALSE，则可以跳过此步骤。请参阅政策:policy:CMP0074。

   • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/lib for each <prefix> in the <PackageName>_ROOT CMake variable and the <PackageName>_ROOT environment variable if called from within a find module loaded by find_package(<PackageName>)

2. 在特定于 cmake 的缓存变量中指定的搜索路径。这些旨在与“-DVAR=value”一起在命令行上使用。这些值被解释为:ref:分号分隔的列表 <CMake Language Lists>。如果传递了 NO_CMAKE_PATH 或通过将 CMAKE_FIND_USE_CMAKE_PATH 设置为 FALSE 可以跳过这一步。

   • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH

   • CMAKE_LIBRARY_PATH

   • CMAKE_FRAMEWORK_PATH

3. 在特定于 cmake 的环境变量中指定的搜索路径。这些旨在在用户的 shell 配置中设置，因此使用主机的本机路径分隔符（Windows 上为“;”，UNIX 上为“ :”）。如果传递了 NO_CMAKE_ENVIRONMENT_PATH 或通过将 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH 设置为 FALSE 可以跳过这一步。

   • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH

   • CMAKE_LIBRARY_PATH

   • CMAKE_FRAMEWORK_PATH

4. 搜索由“HINTS”选项指定的路径。这些应该是系统自省计算出的路径，例如由已找到的另一个项目的位置提供的提示。硬编码的猜测应该用 PATHS 选项指定。

5. 搜索标准系统环境变量。如果传递了 NO_SYSTEM_ENVIRONMENT_PATH 或通过将 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH 设置为 FALSE 可以跳过这一步。

   • The directories in LIB and PATH.

   • On Windows hosts: <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/lib for each <prefix>/[s]bin in PATH, and <entry>/lib for other entries in PATH.

6. 搜索在当前系统的平台文件中定义的 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，则可以跳过所有这些位置。

   • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH

   • CMAKE_SYSTEM_LIBRARY_PATH

   • CMAKE_SYSTEM_FRAMEWORK_PATH

   这些变量包含的平台路径是通常包含已安装软件的位置。一个例子是 /usr/local 用于基于 UNIX 的平台。

7. 搜索由 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_LIBRARY 来调整默认行为。可以使用选项在每次调用的基础上手动覆盖此行为：

CMAKE_FIND_ROOT_PATH_BOTH

按上述顺序搜索。

NO_CMAKE_FIND_ROOT_PATH

不要使用 CMAKE_FIND_ROOT_PATH 变量。

ONLY_CMAKE_FIND_ROOT_PATH

仅搜索重新根目录和以下目录 CMAKE_STAGING_PREFIX。

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

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

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

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

赋予 NAMES 选项的每个库名称首先被视为库文件名，然后被视为具有特定于平台的前缀（例如 lib）和后缀（例如 .so）。因此，可以直接指定库文件名，例如 libfoo.a。这可用于在类 UNIX 系统上定位静态库。

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

如果设置了 CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX 变量，所有搜索路径将被正常测试，并附加后缀，并将所有匹配的 lib/ 替换为 lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/。此变量覆盖 FIND_LIBRARY_USE_LIB32_PATHS、 FIND_LIBRARY_USE_LIBX32_PATHS 和 FIND_LIBRARY_USE_LIB64_PATHS 全局属性。

如果 FIND_LIBRARY_USE_LIB32_PATHS 全局属性被设置，所有搜索路径将被正常测试，附加 32/，并将所有匹配的 lib/ 替换为 lib32/。如果至少启用了 project() 命令支持的一种语言，则此属性会自动为已知需要它的平台设置。

如果 FIND_LIBRARY_USE_LIBX32_PATHS 全局属性被设置，所有搜索路径将被正常测试，附加 x32/，并将所有匹配的 lib/ 替换为 libx32/。如果至少启用了 project() 命令支持的一种语言，则此属性会自动为已知需要它的平台设置。

如果 FIND_LIBRARY_USE_LIB64_PATHS 全局属性被设置，所有搜索路径将被正常测试，附加 64/，并将所有匹配的 lib/ 替换为 lib64/。如果至少启用了 project() 命令支持的一种语言，则此属性会自动为已知需要它的平台设置。