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>，并通过 IMPORT 生成的目标的 INTERFACE_LINK_LIBRARIES 目标属性公开。

无法通过常规的基于目标的命令来修改或定位这些 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.org pkg-config 实现使用的原始 PKG_CONFIG_* 环境变量集。

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

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

  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）包文件的搜索行为。这些是带有 “-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 包变量。

PREFIX <name>

指定前缀会创建一个独立于先前填充目标的 pkg-config 目标集合。这使得给定包的多个版本能够共存，例如来自不同 sysroot 的包。

默认前缀为空字符串。

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

以下变量将根据包文件的内容进行填充：

变量	类型	定义
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 环境变量，则标志被保留，否则在标志处理过程中它们会被过滤。

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 允许在不导入原生 CMake 目标的情况下，手动控制给定包的 Requires 列表的解析。一旦填充，包及其依赖项将用于解析所有未来的 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>])

创建一个原生的 CMake IMPORTED 目标，可以通过 target_link_libraries() 链接到该目标。默认情况下，这个新目标被命名为 PkgConfig::<package>。

PKGCONFIG_<package>_FOUND 变量将被设置，以指示是否找到了该包。

名称

覆盖创建的 CMake 目标的名称为 PkgConfig::<name>。这不会影响 PKGCONFIG_<package>_FOUND 变量。