cmake_pkg_config¶
在版本 3.31 中添加。
处理 pkg-config 格式的包文件。
概要¶
cmake_pkg_config(EXTRACT <package> [<version>] [...]) cmake_pkg_config(POPULATE <package> [<version>] [...]) cmake_pkg_config(IMPORT <package> [<version>] [...])
简介¶
此命令可从 pkg-config 格式的包文件原生生成 CMake 变量和目标,无需调用甚至无需 pkg-config 实现的存在。<package> 是包文件的绝对路径,或是使用典型 pkg-config 搜索模式搜索的包名称。可选的 <version> 字符串具有与 pkg-config 样式版本说明符相同的格式和语义,不同之处在于如果未指定比较运算符,则假定为 =。
PkgConfig 目标¶
cmake_pkg_config
可能会在全局作用域中递归生成类似目标的名称,以解析包的 IMPORT
或 POPULATE
命令。这些名称的形式为 @foreign_pkgcfg::[<prefix>_]<package>
,并通过 INTERFACE_LINK_LIBRARIES
目标属性(由 IMPORT
生成的目标)公开。
无法通过正常的基于目标的命令修改或寻址这些 pkg-config 本机目标。通过 POPULATE
命令可以有限地控制它们的生成,但修改通常应在相应的包文件中进行,而不是在 CMake 中下游进行。
Pkg-config 目标在命令之间重复使用。一旦给定的包名称通过 POPULATE
或 IMPORT
(但不是 EXTRACT
)解析,这些命令未来对相应包名称的所有请求都将解析到先前生成的 pkg-config 目标。
EXTRACT
始终执行完整的包名称查找,以允许在自定义依赖项管理方案中搜索同一包的多个安装。
通用选项¶
此命令有多个签名,其中一些选项是通用的。它们是
EXACT
/QUIET
/REQUIRED
EXACT
选项要求版本字符串完全匹配(包括空字符串,如果未提供版本),覆盖了典型的 pkg-config 版本比较算法。这将忽略附加到版本字符串的任何比较运算符。QUIET
选项禁用信息消息,包括指示未找到包(如果它不是REQUIRED
)的消息。REQUIRED
选项在未找到包时会停止处理并显示错误消息。STRICTNESS <mode>
指定在解析和解析期间将如何严格验证包文件的内容。在提供的严格模式下,无效文件将导致命令失败。可能的模式是
STRICT
:严格镜像原始 FDO pkg-config 的行为。变量和关键字必须是唯一的。变量必须在使用前定义。Name、Description 和 Version 关键字必须存在。文件的整体结构必须有效且可解析。PERMISSIVE
:严格镜像 pkgconf 实现的行为。重复的变量将被覆盖。重复的关键字将被附加。未定义的变量解析为空字符串。Name、Description 和 Version 关键字必须存在。文件的整体结构必须有效且可解析。BEST_EFFORT
:与PERMISSIVE
在重复或未初始化变量和关键字方面的行为相同,但在任何情况下都不会失败。需要 BEST_EFFORT 的包文件将在所有其他主要实现下验证失败,应予以修复。
默认严格性为
PERMISSIVE
。ENV_MODE
指定在运行给定命令时将查询哪些环境变量。可能的模式是
FDO
:仅查询 freedesktop.orgpkg-config
实现使用的原始PKG_CONFIG_*
环境变量集。PKGCONF
:查询pkgconf
实现使用的更广泛的环境变量集。IGNORE
:完全忽略环境变量的存在、不存在和值。在所有情况下,如果查询环境变量,它都被视为已定义,但其值为空字符串(就操作而言)。这不会修改当前环境。对于布尔型环境变量,例如PKG_CONFIG_ALLOW_*
,这意味着它们被评估为真值。PKG_CONFIG_SYSROOT_PATH
是一个小小的例外。当使用ENV_MODE IGNORE
时,默认情况下不会发生根路径前置,并且pc_sysrootdir
仍默认为/
。
目标生成子命令始终忽略标志过滤环境变量。默认环境模式是
PKGCONF
。PC_LIBDIR <path>...
覆盖包文件的默认搜索位置;也用于派生
pc_path
包变量。未提供此选项时,默认库目录是以下值中第一个可用的值
CMAKE_PKG_CONFIG_PC_LIB_DIRS
PKG_CONFIG_LIBDIR
环境变量pkg-config --variable pc_path pkg-config
的输出平台相关的默认值
PC_PATH <path>...
覆盖将被添加到搜索路径前面的补充包文件目录;也用于派生
pc_path
包变量。未提供此选项时,默认路径是以下值中第一个可用的值
CMAKE_PKG_CONFIG_PC_PATH
PKG_CONFIG_PATH
环境变量空列表
DISABLE_UNINSTALLED <bool>
覆盖“未安装”包文件的搜索行为。这些是带有“-uninstalled”后缀的包文件,描述了直接从构建树集成的包。
通常,此类包文件的优先级高于“已安装”包。当
DISABLE_UNINSTALLED
为 true 时,禁用搜索“未安装”包。未提供此选项时,默认搜索行为由以下值中第一个可用的值确定
CMAKE_PKG_CONFIG_DISABLE_UNINSTALLED
如果定义了
PKG_CONFIG_DISABLE_UNINSTALLED
环境变量,则禁用搜索,否则启用搜索。
PC_SYSROOT_DIR <path>
覆盖将预置到
-I
编译标志和-L
库搜索位置指定的路径的根路径;也用于派生pc_sysrootdir
包变量。未提供此选项时,默认根路径由以下值中第一个可用的值提供
CMAKE_PKG_CONFIG_SYSROOT_DIR
PKG_CONFIG_SYSROOT_DIR
环境变量如果没有可用的根路径,则不会在包含或库目录路径前添加任何内容,并且
pc_sysrootdir
将设置为/
TOP_BUILD_DIR <path>
覆盖用于派生
pc_top_builddir
包变量的顶级构建目录路径。未提供此选项时,默认顶级构建目录路径是以下值中第一个可用的值
CMAKE_PKG_CONFIG_TOP_BUILD_DIR
PKG_CONFIG_TOP_BUILD_DIR
环境变量如果没有可用的顶级构建目录路径,则不设置
pc_top_builddir
包变量
PREFIX <name>
指定前缀会创建独立的 pkg-config 目标集合,与先前填充的目标分离。这使得给定包的多个版本可以共存,例如来自不同系统根的包。
默认前缀为空字符串。
BIND_PC_REQUIRES <<name>=<target>>...
一个
<name>=<target>
对列表,name
是包名称,它出现在 pkg-config 文件的Requires
列表中,target
是 CMake 本机目标名称(而不是 pkg-config 目标)。当给定包名称出现在包的
Requires
列表中时,它将与关联的 CMake 目标一起实现。此行为适用于 pkg-config 图中所有尚未填充的依赖项。
签名¶
- cmake_pkg_config(EXTRACT <package> [<version>] [...])¶
在版本 3.31 中添加。
将包的内容提取到变量中。
cmake_pkg_config(EXTRACT <package> [<version>] [REQUIRED] [EXACT] [QUIET] [SYSTEM_INCLUDE_DIRS <path>...] [SYSTEM_LIBRARY_DIRS <path>...] [ALLOW_SYSTEM_INCLUDES <bool>] [ALLOW_SYSTEM_LIBS <bool>] [STRICTNESS <mode>] [ENV_MODE <mode>] [PC_LIBDIR <path>...] [PC_PATH <path>...] [DISABLE_UNINSTALLED <bool>] [PC_SYSROOT_DIR <path>] [TOP_BUILD_DIR <path>])
将从包文件的内容中填充以下变量
变量 |
类型 |
定义 |
---|---|---|
|
字符串 |
|
|
字符串 |
|
|
字符串 |
|
|
列表 |
|
|
列表 |
|
|
列表 |
|
|
字符串 |
|
|
列表 |
来自 |
|
列表 |
来自 |
|
字符串 |
|
|
列表 |
来自 |
|
列表 |
来自 |
|
列表 |
来自 |
|
* |
|
SYSTEM_INCLUDE_DIRS
为了对
CMAKE_PKG_CONFIG_CFLAGS
及派生变量中的包含目录进行标志混淆,此选项会覆盖“系统”目录。未提供此选项时,默认目录由以下值中第一个可用的值提供
CMAKE_PKG_CONFIG_SYS_INCLUDE_DIRS
PKG_CONFIG_SYSTEM_INCLUDE_PATH
环境变量pkgconf --variable pc_system_includedirs pkg-config
的输出平台相关的默认值
此外,当
ENV_MODE
为PKGCONF
时,如果可用,CMAKE_PKG_CONFIG_PKGCONF_INCLUDES
变量将被连接到列表中。如果不可用,将查询并连接以下环境变量CPATH
C_INCLUDE_PATH
CPLUS_INCLUDE_PATH
OBJC_INCLUDE_PATH
INCLUDE
(仅限 Windows)
SYSTEM_LIBRARY_DIRS
覆盖“系统”目录,用于在
CMAKE_PKG_CONFIG_LIBS
和派生变量中对库目录进行标志处理。未提供此选项时,默认目录由以下值中第一个可用的值提供
CMAKE_PKG_CONFIG_SYS_LIB_DIRS
PKG_CONFIG_SYSTEM_LIBRARY_PATH
环境变量pkgconf --variable pc_system_libdirs pkg-config
的输出平台相关的默认值
此外,当
ENV_MODE
为PKGCONF
时,如果可用,CMAKE_PKG_CONFIG_PKGCONF_LIB_DIRS
变量将被连接到列表中。如果不可用,将查询并连接LIBRARY_PATH
环境变量。ALLOW_SYSTEM_INCLUDES
在
CMAKE_PKG_CONFIG_CFLAGS
和派生变量中,在对包含目录进行标志处理时保留“系统”目录。未提供此选项时,默认值由以下值中第一个可用的值确定
CMAKE_PKG_CONFIG_ALLOW_SYS_INCLUDES
如果定义了
PKG_CONFIG_ALLOW_SYSTEM_CFLAGS
环境变量,则标志在标志处理期间保留,否则过滤掉。
ALLOW_SYSTEM_LIBS
在
CMAKE_PKG_CONFIG_LIBS
和派生变量中,在对库目录进行标志处理时保留“系统”目录。未提供此选项时,默认值由以下值中第一个可用的值确定
CMAKE_PKG_CONFIG_ALLOW_SYS_LIBS
如果定义了
PKG_CONFIG_ALLOW_SYSTEM_LIBS
环境变量,则标志在标志处理期间保留,否则过滤掉。
- cmake_pkg_config(POPULATE <package> [<version>] [...])¶
在 4.1 版本中新增。
在 pkg-config 目标命名空间中填充包
cmake_pkg_config(POPULATE <package> [<version>] [REQUIRED] [EXACT] [QUIET] [PREFIX <prefix>] [BIND_PC_REQUIRES <<name>=<target>>...] [STRICTNESS <mode>] [ENV_MODE <mode>] [PC_LIBDIR <path>...] [PC_PATH <path>...] [DISABLE_UNINSTALLED <bool>] [PC_SYSROOT_DIR <path>] [TOP_BUILD_DIR <path>])
POPULATE
允许手动控制给定包的 Requires
列表的解析,而无需导入到本机 CMake 目标。一旦填充,包及其依赖项将用于所有未来 POPULATE
和 IMPORT
命令的解析。
将设置 PKGCONFIG_<package>_FOUND
变量以指示是否找到包。
- cmake_pkg_config(IMPORT <package> [<version>] [...])¶
在 4.1 版本中新增。
将 pkg-config 目标导入为 CMake
IMPORTED
目标cmake_pkg_config(IMPORT <package> [<version>] [REQUIRED] [EXACT] [QUIET] [NAME <name>] [PREFIX <prefix>] [BIND_PC_REQUIRES <<name>=<target>>...] [STRICTNESS <mode>] [ENV_MODE <mode>] [PC_LIBDIR <path>...] [PC_PATH <path>...] [DISABLE_UNINSTALLED <bool>] [PC_SYSROOT_DIR <path>] [TOP_BUILD_DIR <path>])
创建可通过 target_link_libraries()
链接的本机 CMake IMPORTED
目标。此新目标默认命名为 PkgConfig::<package>
。
将设置 PKGCONFIG_<package>_FOUND
变量以指示是否找到包。
名称
将创建的 CMake 目标的名称覆盖为
PkgConfig::<name>
。这 不 影响PKGCONFIG_<package>_FOUND
变量。