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

此命令用于查找库。

在搜索之前，find_library 会检查变量 `<VAR>` 是否已定义。如果变量未定义，则会执行搜索。如果变量已定义且其值为 `NOTFOUND`，或者以 `-NOTFOUND` 结尾，则会执行搜索。如果变量包含任何其他值，则不会执行搜索。

注意

VAR 被视为已定义，如果它在当前作用域中可用。有关作用域的详细信息以及普通变量和缓存条目交互的信息，请参阅 cmake-language(7) 变量文档。

搜索结果将存储在名为 `<VAR>` 的缓存条目中。未来调用 find_library 时，如果指定了相同的 `<VAR>`，将检查此缓存条目。此优化可确保成功的搜索不会被重复执行，除非缓存条目被 unset()。

如果找到库，则缓存条目 `<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 版本新增。

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

注意

find_library 仍会像往常一样检查 `<VAR>`，首先检查变量，然后检查缓存条目。如果其中任何一个指示了之前的成功搜索，则不会执行搜索。

警告

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

REQUIRED

在 3.18 版本中新增。

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

在版本 4.1 中添加: 当启用 `CMAKE_FIND_REQUIRED 变量时，每个 find_library 命令将被视为 `REQUIRED`。

OPTIONAL

在 4.1 版本中新增。

忽略 CMAKE_FIND_REQUIRED 的值，并在未找到任何内容时继续执行而不会出现错误消息。与 REQUIRED 不兼容。

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

如果从 find 模块或由 find_package(<PackageName>) 调用加载的任何其他脚本中调用，则搜索特定于正在查找的当前包的路径。请参阅策略 CMP0074。

3.12 版本新增。

具体来说，按以下顺序搜索以下变量指定的路径
1. CMake 变量 <PackageName>_ROOT，其中 <PackageName> 是区分大小写的包名称。
2. CMake 变量 <PACKAGENAME>_ROOT，其中 <PACKAGENAME> 是大写的包名称。请参阅策略 CMP0144。
  
  在 3.27 版本中新增。
3. 环境变量 <PackageName>_ROOT，其中 <PackageName> 是区分大小写的包名称。
4. 环境变量 <PACKAGENAME>_ROOT，其中 <PACKAGENAME> 是大写的包名称。请参阅策略 CMP0144。
  
  在 3.27 版本中新增。
包根变量被维护为一个堆栈，因此如果从嵌套的 find 模块或 config 包调用，来自父级 find 模块或 config 包的根路径将在来自当前模块或包的路径之后进行搜索。换句话说，搜索顺序将是 `<CurrentPackage>_ROOT`、`ENV{<CurrentPackage>_ROOT}`、`<ParentPackage>_ROOT`、`ENV{<ParentPackage>_ROOT}` 等。如果传递了 `NO_PACKAGE_ROOT_PATH` 或将 CMAKE_FIND_USE_PACKAGE_ROOT_PATH 设置为 `FALSE`，则可以跳过此操作。
- `<prefix>/lib/<arch>`（如果设置了 CMAKE_LIBRARY_ARCHITECTURE），以及 `<prefix>/lib`（对于 <PackageName>_ROOT CMake 变量和 <PackageName>_ROOT 环境变量中的每个 `<prefix>`），如果从由 find_package(<PackageName>) 加载的 find 模块中调用。
在 CMake 特定缓存变量中指定的搜索路径。这些变量旨在通过命令行与 -DVAR=value 一起使用。这些值被解释为分号分隔的列表。如果传递了 NO_CMAKE_PATH 或将 CMAKE_FIND_USE_CMAKE_PATH 设置为 FALSE，则可以跳过此操作。
- `<prefix>/lib/<arch>`（如果设置了 CMAKE_LIBRARY_ARCHITECTURE），以及 `<prefix>/lib`（对于 CMAKE_PREFIX_PATH 中的每个 `<prefix>`）。
- CMAKE_LIBRARY_PATH
- CMAKE_FRAMEWORK_PATH
在 CMake 特定环境变量中指定的搜索路径。这些变量旨在在用户的 shell 配置中设置，因此使用主机本机路径分隔符（Windows 上为 ;，UNIX 上为 :）。如果传递了 NO_CMAKE_ENVIRONMENT_PATH 或将 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH 设置为 FALSE，则可以跳过此操作。
- `<prefix>/lib/<arch>`（如果设置了 CMAKE_LIBRARY_ARCHITECTURE），以及 `<prefix>/lib`（对于 CMAKE_PREFIX_PATH 中的每个 `<prefix>`）。
- 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 中移除。
搜索当前系统平台文件定义的 cmake 变量。搜索 `CMAKE_INSTALL_PREFIX` 和 `CMAKE_STAGING_PREFIX` 可以通过传递 `NO_CMAKE_INSTALL_PREFIX` 或将 CMAKE_FIND_USE_INSTALL_PREFIX 设置为 `FALSE` 来跳过。如果传递 `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`），这些前缀和后缀由变量 CMAKE_FIND_LIBRARY_PREFIXES 和 CMAKE_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_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¶

上一主题

下一主题

本页