find_package命令:找到(通常对于项目来说是外部的东西)并加载包特定的细节。
一、搜寻模式
搜寻模式是cmake搜索所需要包的方法,可分为模块模式(Module mode)和(配置模式)Config Mode。
1.1 模块模式(Module mode)
在这种模式下,CMake将会搜寻一个名字叫做Find<PackageName>.cmake
的文件。
- CMAKE_MODULE_PATH列表
- CMake安装目录
如果找到了这个文件,CMake将会读取并且处理它(比如说,查找包、检查版本,产生一些必要信息)。Find<PackageName>.cmake
通常不是包本身提供的,更多的是系统或者CMake提供的,甚至有可能是项目通过find_package()
命令提供的。注意,Module mode只支持basic command signature。
CMAKE_MODULE_PATH是一个逗号分割的列表,用来指定CMake 模块搜索路径,有两个命令可能会使用到它,分别是
include()
和find_package
。默认情况,这个列表为空,通常是在项目中设置的。
1.2 配置模式(Config mode)
在这个模式下,CMake尝试寻找名为带有config的后缀为cmake文件(<lowercasePackageName>-config.cmake
<PackageName>Config.cmake
<lowercasePackageName>-config-version.cmake
<PackageName>ConfigVersion.cmake
),这个搜索顺序比模块模式要复杂的多,具体可以参考https://cmake.org/cmake/help/latest/command/find_package.html#search-procedure ,相较于上一个模式,配置模式更加可靠因为模块模式可能找到一些过期的库,而且没办法选择版本,本模式支持Basic Signature和Full Signature形式。
二、特征(Signature)
2.1 基础特征(Basic Signature)
find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
[REQUIRED] [[COMPONENTS] [components...]]
[OPTIONAL_COMPONENTS components...]
[NO_POLICY_SCOPE])
PackageName
待查找的包名[version]
版本号major[.minor[.patch[.tweak]]]
versionMin...[<]versionMax
[EXACT]
要求版本完全匹配[QUIET]
禁用信息通知[MODULE]
这个命令采用MODE模式寻找包[REQUIRED]
可以省略,后面接组件名称[[COMPONENTS] [components...]]
组件[OPTIONAL_COMPONENTS components...]
可选组件
2.2 全特征(Full Signature)
find_package(<PackageName> [version] [EXACT] [QUIET]
[REQUIRED] [[COMPONENTS] [components...]]
[OPTIONAL_COMPONENTS components...]
[CONFIG|NO_MODULE]
[NO_POLICY_SCOPE]
[NAMES name1 [name2 ...]]
[CONFIGS config1 [config2 ...]]
[HINTS path1 [path2 ... ]]
[PATHS path1 [path2 ... ]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[NO_DEFAULT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_PACKAGE_REGISTRY]
[NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
[NO_CMAKE_SYSTEM_PATH]
[NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH])
PackageName
模块名version
版本号[EXACT]
要求版本完全匹配[QUIET]
禁用信息通知[REQUIRED]
可以省略,后面接组件名称[[COMPONENTS] [components...]]
组件[OPTIONAL_COMPONENTS components...]
可选组件[CONFIG|NO_MODULE]
这个命令采用CONFIG模式寻找包[NAMES name1 [name2 ...]]
如果该选项被指定,那么名称将会替代Packagename[CONFIGS config1 [config2 ...]]
NAME对应的选项?
三、包文件接口变量
一旦找到了这个包,CMake将会提供以下信息:
变量名 | 含义 |
---|---|
CMAKE_FIND_PACKAGE_NAME | 包名称 |
<PackageName>_FIND_REQUIRED | REQUIED选项是否设定 |
<PackageName>_FIND_QUIETLY | QUIETLY是否设定 |
<PackageName>_FIND_VERSION | 完整的请求版本名称 |
<PackageName>_FIND_COMPONENTS | 完整的组件列表 |