cmake_pkg_config

版本 3.31 新增。

处理 pkg-config 格式的包文件。

概要

cmake_pkg_config(EXTRACT <package> [<version>] [...])

简介

此命令原生从 pkg-config 格式的包文件生成 CMake 变量和目标，无需调用甚至不需要 pkg-config 实现的存在。<package> 可以是包文件的绝对路径，或者是要使用典型的 pkg-config 搜索模式搜索的包名称。可选的 <version> 字符串具有与 pkg-config 风格的版本说明符相同的格式和语义，但如果未指定比较运算符，则假定为 =。

此命令有多个签名，其中一些选项在它们之间是通用的。它们是

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.org pkg-config 实现使用的原始 PKG_CONFIG_* 环境变量集。

• PKGCONF： 查询 pkgconf 实现使用的更广泛的环境变量集。

• IGNORE： 完全忽略环境变量的存在、缺失和值。在所有情况下，将查询环境变量，并将其视为已定义，但为了操作的目的，其值为空字符串。这不会修改当前环境。对于布尔环境变量，例如 PKG_CONFIG_ALLOW_*，这意味着它们被评估为真值。

  PKG_CONFIG_SYSROOT_PATH 是一个小的例外。当使用 ENV_MODE IGNORE 时，默认情况下不会发生根路径前置，并且 pc_sysrootdir 仍然默认为 /。

目标生成子命令始终忽略标志过滤环境变量。默认环境模式是 PKGCONF。

PC_LIBDIR <path>...

覆盖包文件的默认搜索位置；也用于派生 pc_path 包变量。

当未提供此选项时，默认库目录是以下值中的第一个可用值

1. CMAKE_PKG_CONFIG_PC_LIB_DIRS

2. PKG_CONFIG_LIBDIR 环境变量

3. pkg-config --variable pc_path pkg-config 的输出

4. 平台相关的默认值

PC_PATH <path>...

覆盖将前置到搜索路径的补充包文件目录；也用于派生 pc_path 包变量。

当未提供此选项时，默认路径是以下值中的第一个可用值

1. CMAKE_PKG_CONFIG_PC_PATH

2. PKG_CONFIG_PATH 环境变量

3. 空列表

DISABLE_UNINSTALLED <bool>

覆盖对“未安装”包文件的搜索行为。这些是带有“-uninstalled”后缀的包文件，描述了直接从构建树集成的包。

通常，此类包文件比“已安装”包具有更高的优先级。当 DISABLE_UNINSTALLED 为真时，禁用搜索“未安装”包。

当未提供此选项时，默认搜索行为由以下值中的第一个可用值确定

1. CMAKE_PKG_CONFIG_DISABLE_UNINSTALLED

2. 如果定义了 PKG_CONFIG_DISABLE_UNINSTALLED 环境变量，则禁用搜索，否则启用搜索。

PC_SYSROOT_DIR <path>

覆盖根路径，该路径将前置到 -I 编译标志和 -L 库搜索位置指定的路径；也用于派生 pc_sysrootdir 包变量。

当未提供此选项时，默认根路径由以下值中的第一个可用值提供

1. CMAKE_PKG_CONFIG_SYSROOT_DIR

2. PKG_CONFIG_SYSROOT_DIR 环境变量

3. 如果根路径不可用，则不会将任何内容前置到包含或库目录路径，并且 pc_sysrootdir 将设置为 /

TOP_BUILD_DIR <path>

覆盖用于派生 pc_top_builddir 包变量的顶级构建目录路径。

当未提供此选项时，默认顶级构建目录路径是以下值中的第一个可用值

1. CMAKE_PKG_CONFIG_TOP_BUILD_DIR

2. PKG_CONFIG_TOP_BUILD_DIR 环境变量

3. 如果顶级构建目录路径不可用，则不会设置 pc_top_builddir 包变量

签名

cmake_pkg_config(EXTRACT <package> [<version>] [...])

将包的内容提取到变量中。

cmake_pkg_config(EXTRACT <package> [<version>]
                [REQUIRED] [EXACT] [QUIET]
                [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 <path>...]
                [SYSTEM_LIBRARY_DIRS <path>...]
                [ALLOW_SYSTEM_INCLUDES <bool>]
                [ALLOW_SYSTEM_LIBS <bool>])

以下变量将从包文件的内容填充

变量	类型	定义
CMAKE_PKG_CONFIG_NAME	字符串	Name 关键字的值
CMAKE_PKG_CONFIG_DESCRIPTION	字符串	Description 关键字的值
CMAKE_PKG_CONFIG_VERSION	字符串	Version 关键字的值
CMAKE_PKG_CONFIG_PROVIDES	列表	Provides 关键字的值
CMAKE_PKG_CONFIG_REQUIRES	列表	Requires 关键字的值
CMAKE_PKG_CONFIG_CONFLICTS	列表	Conflicts 关键字的值
CMAKE_PKG_CONFIG_CFLAGS	字符串	CFlags / Cflags 关键字的值
CMAKE_PKG_CONFIG_INCLUDES	列表	来自 CMAKE_PKG_CONFIG_CFLAGS 的所有 -I 前缀的标志
CMAKE_PKG_CONFIG_COMPILE_OPTIONS	列表	来自 CMAKE_PKG_CONFIG_CFLAGS 的所有未以 -I 为前缀的标志
CMAKE_PKG_CONFIG_LIBS	字符串	Libs 关键字的值
CMAKE_PKG_CONFIG_LIBDIRS	列表	来自 CMAKE_PKG_CONFIG_LIBS 的所有 -L 前缀的标志
CMAKE_PKG_CONFIG_LIBNAMES	列表	来自 CMAKE_PKG_CONFIG_LIBS 的所有 -l 前缀的标志
CMAKE_PKG_CONFIG_LINK_OPTIONS	列表	来自 CMAKE_PKG_CONFIG_LIBS 的所有未以 -L 或 -l 为前缀的标志
CMAKE_PKG_CONFIG_*_PRIVATE	*	CFLAGS / LIBS / REQUIRES 及其派生项，但采用 .private 后缀形式

SYSTEM_INCLUDE_DIRS

覆盖“系统”目录，用于标志修饰 CMAKE_PKG_CONFIG_CFLAGS 和派生变量中的包含目录。

当未提供此选项时，默认目录由以下值中的第一个可用值提供

1. CMAKE_PKG_CONFIG_SYS_INCLUDE_DIRS

2. PKG_CONFIG_SYSTEM_INCLUDE_PATH 环境变量

3. pkgconf --variable pc_system_includedirs pkg-config 的输出

4. 平台相关的默认值

此外，当 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 和派生变量中的库目录。

当未提供此选项时，默认目录由以下值中的第一个可用值提供

1. CMAKE_PKG_CONFIG_SYS_LIB_DIRS

2. PKG_CONFIG_SYSTEM_LIBRARY_PATH 环境变量

3. pkgconf --variable pc_system_libdirs pkg-config 的输出

4. 平台相关的默认值

此外，当 ENV_MODE 为 PKGCONF 时，如果可用，CMAKE_PKG_CONFIG_PKGCONF_LIB_DIRS 变量将连接到列表中。如果不可用，将查询并连接 LIBRARY_PATH 环境变量。

ALLOW_SYSTEM_INCLUDES

在标志修饰 CMAKE_PKG_CONFIG_CFLAGS 和派生变量中的包含目录期间，保留“系统”目录。

当未提供此选项时，默认值由以下值中的第一个可用值确定

1. CMAKE_PKG_CONFIG_ALLOW_SYS_INCLUDES

2. 如果定义了 PKG_CONFIG_ALLOW_SYSTEM_CFLAGS 环境变量，则保留标志，否则在标志修饰期间会对其进行过滤。

ALLOW_SYSTEM_LIBS

在标志修饰 CMAKE_PKG_CONFIG_LIBS 和派生变量中的库目录期间，保留“系统”目录。

当未提供此选项时，默认值由以下值中的第一个可用值确定

1. CMAKE_PKG_CONFIG_ALLOW_SYS_LIBS

2. 如果定义了 PKG_CONFIG_ALLOW_SYSTEM_LIBS 环境变量，则保留标志，否则在标志修饰期间会对其进行过滤。