FindPkgConfig¶

CMake 的 pkg-config 模块。

查找 pkg-config 可执行文件，并提供在 CMake 中使用它的命令。

find_package(PkgConfig [<version>] [QUIET] [REQUIRED] [...])

pkg-config 是一个用于配置构建依赖信息的命令行程序。它最初由 FreeDesktop 开发，也有多种实现，例如 pkgconf、u-config 等。它从所谓的 PC 元数据文件（<module-name>.pc）读取包数据，这些文件可能随包一起安装。本模块是 pkg-config 命令行可执行程序的一个包装器。

结果变量¶

此模块定义了以下变量

PkgConfig_FOUND: 3.3 版本中新增。

一个布尔值，指示是否找到了（指定版本的）pkg-config 可执行文件。
PkgConfig_VERSION: 版本 4.2 中添加。

找到的 pkg-config 的版本。
PKG_CONFIG_EXECUTABLE: pkg-config 程序的路径名。
PKG_CONFIG_ARGN: 3.22 版本新增。

要传递给 pkg-config 的参数列表。

PKG_CONFIG_EXECUTABLE 和 PKG_CONFIG_ARGN 均由模块初始化，但可以被用户覆盖。有关这些变量如何初始化的信息，请参阅 Hints。

命令¶

如果找到 pkg-config，则此模块提供以下命令：

pkg_check_modules()
pkg_search_module()
pkg_get_variable()

pkg_check_modules¶

检查所有指定的模块，在调用作用域中设置各种结果变量。

pkg_check_modules(
  <prefix>
  [QUIET]
  [REQUIRED]
  [NO_CMAKE_PATH]
  [NO_CMAKE_ENVIRONMENT_PATH]
  [IMPORTED_TARGET [GLOBAL]]
  <module-spec> [<module-spec>...]
)

参数为

<prefix>

前缀字符串，将附加到指定模块的结果变量之前。

QUIET

给出此参数时，不会打印状态消息。

REQUIRED

给出此参数时，如果任何指定的模块未找到，命令将以错误失败。

NO_CMAKE_PATH, NO_CMAKE_ENVIRONMENT_PATH

3.3 版本中新增。

缓存和环境变量 CMAKE_PREFIX_PATH、CMAKE_FRAMEWORK_PATH 和 CMAKE_APPBUNDLE_PATH 将被添加到 pkg-config 搜索路径中。NO_CMAKE_PATH 和 NO_CMAKE_ENVIRONMENT_PATH 参数分别禁用缓存变量和环境变量的此行为。PKG_CONFIG_USE_CMAKE_PREFIX_PATH 变量设置为 FALSE 可全局禁用此行为。

IMPORTED_TARGET [GLOBAL]

3.7 版本中新增。

此参数将创建一个名为 PkgConfig::<prefix> 的导入目标，该目标可以直接作为参数传递给 target_link_libraries()。它将一次性封装所有指定模块 <module-spec>... 的使用要求。

GLOBAL: 3.13 版本新增。

此参数与 IMPORTED_TARGET 一起使用，并将使导入目标在全局作用域中可用。

版本 3.15 中新增： pkg-config 报告的非库链接器选项存储在 INTERFACE_LINK_OPTIONS 目标属性中。

版本 3.18 中更改：使用 -isystem 指定的包含目录存储在 INTERFACE_INCLUDE_DIRECTORIES 目标属性中。CMake 的先前版本将其保留在 INTERFACE_COMPILE_OPTIONS 属性中。

<module-spec>

每个 <module-spec> 可以是裸模块名（如其 PC 元数据文件名 <module-name>.pc 中定义的）或带有版本约束的模块名（支持运算符 =、<、>、<= 和 >=）。以下是名为 foo 的模块及其各种约束的示例：

foo 匹配任何版本。
foo<2 仅匹配 2 之前的版本。
foo>=3.1 匹配 3.1 或更高版本。
foo=1.2.3 要求 foo 必须是 1.2.3 版本。

结果变量

返回后，以下变量可能会被设置。存在两组值：一组用于常见情况（<XXX> = <prefix>），另一组用于 pkg-config 使用 --static 选项调用时提供的信息（<XXX> = <prefix>_STATIC）。

<XXX>_FOUND: 如果模块存在，则设置为 1 的布尔变量。
<XXX>_LIBRARIES: 仅库列表（不含 -l）。
<XXX>_LINK_LIBRARIES: 库及其绝对路径。
<XXX>_LIBRARY_DIRS: 库的路径（不含 -L）。
<XXX>_LDFLAGS: 所有必需的链接器标志。
<XXX>_LDFLAGS_OTHER: 所有其他链接器标志。
<XXX>_INCLUDE_DIRS: -I 预处理器标志（不含 -I）。
<XXX>_CFLAGS: 所有必需的 cflags。
<XXX>_CFLAGS_OTHER: 其他编译器标志。

除 <XXX>_FOUND 外，如果 pkg-config 返回的相应变量具有多个值，则它们可以是分号分隔的列表。

版本 3.18 中更改：使用 -isystem 指定的包含目录存储在 <XXX>_INCLUDE_DIRS 变量中。CMake 的先前版本将其保留在 <XXX>_CFLAGS_OTHER 中。

有一些特殊变量，其前缀取决于提供的 <module-spec> 的数量。当只有一个 <module-spec> 时，<YYY> 仅为 <prefix>，但如果提供了两个或更多 <module-spec> 项，则 <YYY> 为 <prefix>_<module-name>。

<YYY>_VERSION: 模块的版本。
<YYY>_PREFIX: 模块的前缀目录。
<YYY>_INCLUDEDIR: 模块的包含目录。
<YYY>_LIBDIR: 模块的 lib 目录。

版本 3.8 中更改：对于任何给定的 <prefix>，pkg_check_modules() 可以多次调用，参数不同。CMake 的先前版本缓存并返回第一次成功的结果。

版本 3.16 中更改：如果找不到找到的库的完整路径，但它仍然对链接器可见，则将其作为 -l<name> 传递。CMake 的先前版本在此情况下会失败。

pkg_search_module¶

搜索提供的一个或多个模块规范的第一个成功匹配。

pkg_search_module(
  <prefix>
  [QUIET]
  [REQUIRED]
  [NO_CMAKE_PATH]
  [NO_CMAKE_ENVIRONMENT_PATH]
  [IMPORTED_TARGET [GLOBAL]]
  <module-spec> [<module-spec>...]
)

此命令的行为和参数与 pkg_check_modules() 相同，只是它不是检查所有指定的模块，而是只搜索第一个成功的匹配。

此命令可用于，例如，当某个包可能在不同平台或版本上有多个 <module-spec> 对应于同一包时。

结果变量

此命令除了上述描述的变量外，还会定义相同的变量：

<prefix>_MODULE_NAME: 3.16 版新增。

如果找到模块，则 <prefix>_MODULE_NAME 变量将包含匹配模块的名称。如果需要使用 pkg_get_variable() 命令并为 <module-name> 参数提供 pkg_search_module() 找到的名称，则可以使用此变量。

pkg_get_variable¶

3.4 版本新增。

检索 pkg-config 变量的值，并将其存储在调用作用域的结果变量中。

pkg_get_variable(
  <result-var>
  <module-name>
  <var-name>
  [DEFINE_VARIABLES <key>=<value>...]
)

参数为

<result-var>: 将包含 pkg-config 变量值的 pkg-config 变量的结果变量名。如果 pkg-config 为指定的变量 <var-name> 返回多个值，则 <result-var> 将包含一个分号分隔的列表。
<module-name>: 模块名，如其 PC 元数据文件名（<module-name>.pc）中所定义。
<var-name>: pkg-config PC 元数据文件 <module-name>.pc 中的变量名。
DEFINE_VARIABLES <key>=<value>...: 版本 3.28 新增。

指定键值对，以重新定义影响使用 pkg-config 检索的变量的变量。

提示¶

在调用 find_package(PkgConfig) 之前，此模块接受以下变量以影响其行为：

ENV{PKG_CONFIG_PATH}: pkg-config 将在此路径中搜索其 .pc 文件。默认情况下，pkg-config 工具使用此变量，而 CMake 还提供更通用的 CMAKE_PREFIX_PATH 变量来指定查找包及其 .pc 文件的其他路径。
ENV{PKG_CONFIG}: 版本 3.1 中新增。

环境变量，可以设置为 pkg-config 可执行文件的路径，并可用于初始化 PKG_CONFIG_EXECUTABLE 变量（如果尚未设置）。

PKG_CONFIG_EXECUTABLE

此缓存变量可以设置为 pkg-config 可执行文件的路径。模块内部调用 find_program() 时会使用此变量。

版本 3.22 中更改：如果设置了 PKG_CONFIG 环境变量，则在使用它作为提示时，仅从环境变量中获取第一个参数。

PKG_CONFIG_ARGN

3.22 版本新增。

此缓存变量可以设置为要额外传递给 pkg-config 的参数列表。如果未提供，它将从 PKG_CONFIG 环境变量（如果已设置）初始化。该环境变量中的第一个参数假定为 pkg-config 程序，而之后的所有剩余参数用于初始化 PKG_CONFIG_ARGN。如果未定义此环境变量，则 PKG_CONFIG_ARGN 初始化为空字符串。模块在缓存中设置变量后不会更新它。

PKG_CONFIG_USE_CMAKE_PREFIX_PATH

版本 3.1 中新增。

指定 pkg_check_modules() 和 pkg_search_module() 是否应将 CMAKE_PREFIX_PATH、CMAKE_FRAMEWORK_PATH 和 CMAKE_APPBUNDLE_PATH 缓存和环境变量中的路径添加到 pkg-config 搜索路径。

如果未设置此变量，则默认启用此行为（如果 CMAKE_MINIMUM_REQUIRED_VERSION 为 3.1 或更高版本），否则禁用。

已弃用变量¶

以下变量提供用于向后兼容性

PKG_CONFIG_FOUND: 版本 4.2 已弃用：使用 PkgConfig_FOUND，其值相同。

一个布尔值，指示是否找到了（指定版本的）pkg-config 可执行文件。
PKG_CONFIG_VERSION_STRING: 版本 4.2 已弃用：使用 PkgConfig_VERSION，其值相同。

找到的 pkg-config 的版本。

示例¶

示例：查找 pkg-config¶

查找 pkg-config

find_package(PkgConfig)

查找 pkg-config 并将其设为必需（如果未找到，则处理停止并显示错误消息）。

find_package(PkgConfig REQUIRED)

静默查找 pkg-config，不打印状态消息，这在 find 模块中很常用。

find_package(PkgConfig QUIET)

示例：使用 `pkg_check_modules()`¶

检查任何版本的 glib2。如果找到，输出变量 GLIB2_VERSION 将包含实际找到的版本。

find_package(PkgConfig QUIET)

if(PkgConfig_FOUND)
  pkg_check_modules(GLIB2 glib-2.0)
endif()

以下示例查找 glib2-2.0 的至少版本 2.10。如果找到，输出变量 GLIB2_VERSION 将包含实际找到的版本。

find_package(PkgConfig QUIET)

if(PkgConfig_FOUND)
  pkg_check_modules(GLIB2 glib-2.0>=2.10)
endif()

以下示例查找 glib2-2.0（至少 2.10 版本）和任何版本的 gtk2+-2.0。仅当两者都找到时，FOO 才被视为找到。变量 FOO_glib-2.0_VERSION 和 FOO_gtk+-2.0_VERSION 将被设置为其各自找到的模块版本。

find_package(PkgConfig QUIET)

if(PkgConfig_FOUND)
  pkg_check_modules(FOO glib-2.0>=2.10 gtk+-2.0)
endif()

以下示例要求任何版本的 xrender。

find_package(PkgConfig QUIET REQUIRED)
pkg_check_modules(XRENDER REQUIRED xrender)

成功调用后设置的示例输出变量。

XRENDER_LIBRARIES=Xrender;X11
XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp

示例：使用 `pkg_search_module()`¶

搜索 LibXml2 包，该包可能以不同的模块规范（libxml-2.0 或 libxml2）提供。

find_package(PkgConfig QUIET)

if(PkgConfig_FOUND)
  pkg_search_module(BAR libxml-2.0 libxml2 libxml>=2)
endif()

示例：创建导入目标¶

在以下示例中，将从模块规范创建导入目标，以便在项目中使用，而无需使用 find 模块。这些导入目标可用于，例如，当包已知支持所有受支持平台上的 pkg-config 时。

find_package(PkgConfig QUIET REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk4>=4.14)
target_link_libraries(example PRIVATE PkgConfig::GTK)

示例：使用 `pkg_get_variable()`¶

从 Gobject 包检索 pkg-config 变量 girdir 的值。

find_package(PkgConfig QUIET)

if(PkgConfig_FOUND)
  pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir)
endif()

message(STATUS "${GI_GIRDIR}")

另请参阅¶

使用 cmake_pkg_config() 命令，这是在 CMake 中使用 pkg-config 的一种更现代、更高级的方法，无需安装 pkg-config 可执行文件。
Find Modules 提供了编写 find 模块的详细信息。

FindPkgConfig¶

结果变量¶

命令¶

提示¶

已弃用变量¶

示例¶

示例：查找 pkg-config¶

示例：使用 `pkg_check_modules()`¶

示例：使用 `pkg_search_module()`¶

示例：创建导入目标¶

示例：使用 `pkg_get_variable()`¶

另请参阅¶

目录

上一主题

下一主题

本页

FindPkgConfig¶

结果变量¶

命令¶

提示¶

已弃用变量¶

示例¶

示例：查找 pkg-config¶

示例：使用 pkg_check_modules()¶

示例：使用 pkg_search_module()¶

示例：创建导入目标¶

示例：使用 pkg_get_variable()¶

另请参阅¶

示例：使用 `pkg_check_modules()`¶

示例：使用 `pkg_search_module()`¶

示例：使用 `pkg_get_variable()`¶