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

该命令用于查找库。缓存项或者普通变量（如果指定 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，否则该项目将被接受且搜索将结束。验证器函数进入时，结果变量将保存一个 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，则搜索过程如下

如果从查找模块或由对 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>_ROOTENV{<ParentPackage>_ROOT} 等。如果传递了 NO_PACKAGE_ROOT_PATH 或将 CMAKE_FIND_USE_PACKAGE_ROOT_PATH 设置为 FALSE，则可以跳过此步骤。
- 如果 CMAKE_LIBRARY_ARCHITECTURE 已设置，则为 <prefix>/lib/<arch>，否则对于 <PackageName>_ROOT CMake 变量中的每个 <prefix> 为 <prefix>/lib，如果从 find_package(<PackageName>) 加载的查找模块内部调用了 <PackageName>_ROOT 环境变量也是如此。
cmake 特有缓存变量中指定的搜索路径。这些路径旨在与 -DVAR=value 同时在命令行中使用。这些值会被解释为分号分隔的列表。如果传递了 NO_CMAKE_PATH 或将 CMAKE_FIND_USE_CMAKE_PATH 设为 FALSE，则可以跳过此步骤。
- 如果设置了 CMAKE_LIBRARY_ARCHITECTURE，则为 <prefix>/lib/<arch>，且对于 CMAKE_PREFIX_PATH 中的每个 <prefix>，则为 <prefix>/lib
- CMAKE_LIBRARY_PATH
- CMAKE_FRAMEWORK_PATH
cmake 特有环境变量中指定的搜索路径。这些路径旨在用户 shell 配置中设置，因此这些路径会使用宿主的本机路径分隔符（在 Windows 上为 ;，在 UNIX 上为 :）。如果传递了 NO_CMAKE_ENVIRONMENT_PATH 或将 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH 设为 FALSE，则可以跳过此步骤。
- 如果设置了 CMAKE_LIBRARY_ARCHITECTURE，则为 <prefix>/lib/<arch>，且对于 CMAKE_PREFIX_PATH 中的每个 <prefix>，则为 <prefix>/lib
- CMAKE_LIBRARY_PATH
- CMAKE_FRAMEWORK_PATH
搜索由 HINTS 选项指定的路径。这些路径应该是由系统内省计算出来的路径，比如已经找到的另一项所提供的位置提示。硬编码的猜测应该用 PATHS 选项指定。
搜索标准系统环境变量。如果传递了 NO_SYSTEM_ENVIRONMENT_PATH 或者将 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH 设为 FALSE，则可以跳过此步骤。
- LIB 和 PATH 中的目录。
在 Windows 主机上，CMake 3.3 到 3.27 搜索了其他路径：<prefix>/lib/<arch>（如果 CMAKE_LIBRARY_ARCHITECTURE 已设置），以及 <prefix>/lib（对于 PATH 中的每个 <prefix>/[s]bin），还包括 <entry>/lib（对于 PATH 中的其他项）。CMake 3.28 中移除了此行为。
搜索当前系统 Platform 文件中定义的 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>（如果 CMAKE_LIBRARY_ARCHITECTURE 已设置），以及 <prefix>/lib（对于 CMAKE_SYSTEM_PREFIX_PATH 中的每个 <prefix>）
- CMAKE_SYSTEM_LIBRARY_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_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> 以将框架链接到目标。

已添加至 3.28 版：现在发现的库可以是 .xcframework 文件夹。

如果 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() 命令支持的至少一种语言，则此属性将自动设置。

find_library¶

上一个主题

下一个主题

此页面