find_library

简短签名是

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

此命令用于查找库。将创建一个由 <VAR> 命名的缓存条目,或者如果指定了 NO_CACHE,则创建一个普通变量,以存储此命令的结果。如果找到库,结果将存储在变量中,并且除非清除该变量,否则不会重复搜索。如果未找到任何内容,则结果将为 <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

查询两个视图(6432)并为每个视图生成一个路径。

32_64

查询两个视图(3264)并为每个视图生成一个路径。

HOST

查询与主机架构匹配的注册表:在 64 位 Windows 上为 64,在 32 位 Windows 上为 32

TARGET

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

BOTH

查询两个视图(3264)。顺序取决于以下规则:如果定义了 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_library (result NAMES ... VALIDATOR my_check)

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

DOC

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

NO_CACHE

在 3.21 版本中添加。

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

注意

如果在调用之前已设置变量(作为普通变量或缓存变量),则不会进行搜索。

警告

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

REQUIRED

在 3.18 版本中添加。

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

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

  1. 如果从 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>_ROOTENV{<CurrentPackage>_ROOT}<ParentPackage>_ROOTENV{<ParentPackage>_ROOT} 等。如果传递了 NO_PACKAGE_ROOT_PATH 或将 CMAKE_FIND_USE_PACKAGE_ROOT_PATH 设置为 FALSE,则可以跳过此步骤。

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

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

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

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

    • LIBPATH 中的目录。

    在 Windows 主机上,CMake 3.3 到 3.27 搜索了其他路径:如果设置了 CMAKE_LIBRARY_ARCHITECTURE,则为 <prefix>/lib/<arch>,以及 <prefix>/lib,对于 PATH 中的每个 <prefix>/[s]bin,以及 <entry>/lib,对于 PATH 中的其他条目。CMake 3.28 移除了此行为。

  6. 搜索在当前系统的平台文件中定义的 cmake 变量。如果传递了 NO_CMAKE_INSTALL_PREFIX 或通过将 CMAKE_FIND_USE_INSTALL_PREFIX 设置为 FALSE,则可以跳过 CMAKE_INSTALL_PREFIXCMAKE_STAGING_PREFIX 的搜索。如果传递了 NO_CMAKE_SYSTEM_PATH 或通过将 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH 设置为 FALSE,则可以跳过所有这些位置。

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

  7. 搜索 PATHS 选项或命令的简短版本指定的路径。这些通常是硬编码的猜测。

CMAKE_IGNORE_PATHCMAKE_IGNORE_PREFIX_PATHCMAKE_SYSTEM_IGNORE_PATHCMAKE_SYSTEM_IGNORE_PREFIX_PATH 变量也可能导致忽略上述某些位置。

在 3.16 版本中添加: 添加了 CMAKE_FIND_USE_<CATEGORY>_PATH 变量以全局禁用各种搜索位置。

在 macOS 上,CMAKE_FIND_FRAMEWORKCMAKE_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),如变量 CMAKE_FIND_LIBRARY_PREFIXESCMAKE_FIND_LIBRARY_SUFFIXES 所定义。因此,可以直拉指定库文件名,例如 libfoo.a。这可以用于在类 UNIX 系统上定位静态库。

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

在 3.28 版本中添加: 找到的库现在可以是 .xcframework 文件夹。

如果设置了 CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX 变量,则将正常测试所有搜索路径,附加后缀,并将所有匹配的 lib/ 替换为 lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/。此变量覆盖 FIND_LIBRARY_USE_LIB32_PATHSFIND_LIBRARY_USE_LIBX32_PATHSFIND_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() 命令支持的至少一种语言已启用,则会自动为已知需要它的平台设置此属性。