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] )
此命令用于查找库。将创建一个名为 <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
查询两个视图(
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 时将再次尝试搜索。
版本 4.1 新增: 当启用
CMAKE_FIND_REQUIRED
变量时,每个 find_library 命令都将被视为REQUIRED
。OPTIONAL
在 4.1 版本中新增。
忽略
CMAKE_FIND_REQUIRED
的值,如果未找到任何内容,则继续而不显示错误消息。与REQUIRED
不兼容。
如果指定了 NO_DEFAULT_PATH
,则不会向搜索中添加其他路径。如果未指定 NO_DEFAULT_PATH
,则搜索过程如下
如果从查找模块或通过调用
find_package(<PackageName>)
加载的任何其他脚本中调用,则搜索当前正在查找的包特有的前缀。请参阅策略CMP0074
。3.12 版本新增。
具体来说,按以下顺序搜索以下变量指定的路径
<PackageName>_ROOT
CMake 变量,其中<PackageName>
是大小写保留的包名称。<PACKAGENAME>_ROOT
CMake 变量,其中<PACKAGENAME>
是大写的包名称。请参阅策略CMP0144
。在 3.27 版本中新增。
<PackageName>_ROOT
环境变量,其中<PackageName>
是大小写保留的包名称。<PACKAGENAME>_ROOT
环境变量,其中<PACKAGENAME>
是大写的包名称。请参阅策略CMP0144
。在 3.27 版本中新增。
包根变量以堆栈形式维护,因此如果从嵌套的查找模块或配置包中调用,则父查找模块或配置包的根路径将在当前模块或包的路径之后搜索。换句话说,搜索顺序将是
<CurrentPackage>_ROOT
,ENV{<CurrentPackage>_ROOT}
,<ParentPackage>_ROOT
,ENV{<ParentPackage>_ROOT}
等。如果传递了NO_PACKAGE_ROOT_PATH
或将CMAKE_FIND_USE_PACKAGE_ROOT_PATH
设置为FALSE
,则可以跳过此操作。如果设置了
CMAKE_LIBRARY_ARCHITECTURE
,则为<prefix>/lib/<arch>
,以及当通过find_package(<PackageName>)
加载查找模块时,<PackageName>_ROOT
CMake 变量和<PackageName>_ROOT
环境变量中的每个<prefix>
的<prefix>/lib
在 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 特定的环境变量中指定的搜索路径。这些旨在在用户的 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
搜索
HINTS
选项指定的路径。这些应该是通过系统内省计算出的路径,例如现有项目的位置提供的提示。硬编码的猜测应使用PATHS
选项指定。搜索标准系统环境变量。如果传递了
NO_SYSTEM_ENVIRONMENT_PATH
或将CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH
设置为FALSE
,则可以跳过此操作。LIB
和PATH
中的目录。
在 Windows 主机上,CMake 3.3 到 3.27 搜索了额外的路径:如果设置了
CMAKE_LIBRARY_ARCHITECTURE
,则为<prefix>/lib/<arch>
,以及PATH
中每个<prefix>/[s]bin
的<prefix>/lib
,以及PATH
中其他条目的<entry>/lib
。此行为在 CMake 3.28 中被移除。搜索当前系统平台文件中定义的 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
,则可以跳过所有这些位置。如果设置了
CMAKE_LIBRARY_ARCHITECTURE
,则为<prefix>/lib/<arch>
,以及CMAKE_SYSTEM_PREFIX_PATH
中的每个<prefix>
的<prefix>/lib
这些变量包含的平台路径通常包括已安装的软件位置。例如,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()
命令支持的语言中至少有一种已启用,则此属性会自动为已知需要它的平台设置。