cmake_pkg_config

Added in version 3.31.

Process pkg-config format package files.

Synopsis

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

Introduction

This command generates CMake variables and targets from pkg-config format package files natively, without needing to invoke or even require the presence of a pkg-config implementation. A <package> is either an absolute path to a package file, or a package name to be searched for using the typical pkg-config search patterns. The optional <version> string has the same format and semantics as a pkg-config style version specifier, with the exception that if no comparison operator is specified = is assumed.

PkgConfig Targets

cmake_pkg_config may recursively generate target-like names in the global scope in order to resolve a package IMPORT or POPULATE command. These names take the form of @foreign_pkgcfg::[<prefix>_]<package> and are exposed via the INTERFACE_LINK_LIBRARIES target property of an IMPORT-generated target.

It is not possible to modify or address these pkg-config native targets via normal target-based commands. Limited control over their generation is possible via the POPULATE command, but modification should generally be performed inside the corresponding package file, not downstream in CMake.

Pkg-config targets are reused across commands. Once a given package name has been resolved via POPULATE or IMPORT (but not EXTRACT), all future requests for the corresponding package name by those commands will resolve to the previously generated pkg-config target.

EXTRACT always performs the complete package name lookup in order to allow searches for multiple installations of the same package in custom dependency management schemes.

Common Options

There are multiple signatures for this command, and some of the options are common between them. They are:

EXACT / QUIET / REQUIRED

The EXACT option requests that the version string be matched exactly (including empty string, if no version is provided), overriding the typical pkg-config version comparison algorithm. This will ignore any comparison operator attached to the version string.

The QUIET option disables informational messages, including those indicating that the package cannot be found if it is not REQUIRED. The REQUIRED option stops processing with an error message if the package cannot be found.

STRICTNESS <mode>

Specify how strictly the contents of the package files will be verified during parsing and resolution. An invalid file, under the provided strictness mode, will cause the command to fail. Possible modes are:

• STRICT: Closely mirrors the behavior of the original FDO pkg-config. Variables and keywords must be unique. Variables must be defined before they are used. The Name, Description, and Version keywords must be present. The overall structure of the file must be valid and parsable.

• PERMISSIVE: Closely mirrors the behavior of the pkgconf implementation. Duplicate variables are overridden. Duplicate keywords are appended. Undefined variables resolve to empty strings. The Name, Description, and Version keywords must be present. The overall structure of the file must be valid and parsable.

• BEST_EFFORT: Same behavior as PERMISSIVE with regards to duplicate or uninitialized variables and keywords, but will not fail under any conditions. Package files which require BEST_EFFORT will fail validation under all other major implementations and should be fixed.

The default strictness is PERMISSIVE.

ENV_MODE

Specifies which environment variables will be queried when running a given command. Possible modes are:

• FDO: Queries only the original set of PKG_CONFIG_* environment variables used by the freedesktop.org pkg-config implementation.

• PKGCONF: Queries the more extensive set of environment variables used by the pkgconf implementation.

• IGNORE: Ignores the presence, absence, and value of environment variables entirely. In all cases an environment variable would be queried its treated as defined, but with a value of empty string for the purpose of the operation. This does not modify the current environment. For boolean environment variables, such as PKG_CONFIG_ALLOW_*, this means they are evaluated as truthy.

  PKG_CONFIG_SYSROOT_PATH is a minor exception. When ENV_MODE IGNORE is used, no root path prepending will occur by default and pc_sysrootdir remains defaulted to /.

Target-generating subcommands always ignore flag-filtering environment variables. The default environment mode is PKGCONF.

PC_LIBDIR <path>...

Overrides the default search location for package files; also used to derive the pc_path package variable.

When this option is not provided, the default library directory is the first available of the following values:

1. CMAKE_PKG_CONFIG_PC_LIB_DIRS

2. The PKG_CONFIG_LIBDIR environment variable

3. The output of pkg-config --variable pc_path pkg-config

4. A platform-dependent default value

PC_PATH <path>...

Overrides the supplemental package file directories which will be prepended to the search path; also used to derive the pc_path package variable.

When this option is not provided, the default paths are the first available of the following values:

1. CMAKE_PKG_CONFIG_PC_PATH

2. The PKG_CONFIG_PATH environment variable

3. Empty list

DISABLE_UNINSTALLED <bool>

Overrides the search behavior for "uninstalled" package files. These are package files with an "-uninstalled" suffix which describe packages integrated directly from a build tree.

Normally such package files have higher priority than "installed" packages. When DISABLE_UNINSTALLED is true, searching for "uninstalled" packages is disabled.

When this option is not provided, the default search behavior is determined by the first available of the following values:

1. CMAKE_PKG_CONFIG_DISABLE_UNINSTALLED

2. If the PKG_CONFIG_DISABLE_UNINSTALLED environment variable is defined the search is disabled, otherwise it is enabled.

PC_SYSROOT_DIR <path>

Overrides the root path which will be prepended to paths specified by -I compile flags and -L library search locations; also used to derive the pc_sysrootdir package variable.

When this option is not provided, the default root path is provided by the first available of the following values:

1. CMAKE_PKG_CONFIG_SYSROOT_DIR

2. The PKG_CONFIG_SYSROOT_DIR environment variable

3. If no root path is available, nothing will be prepended to include or library directory paths and pc_sysrootdir will be set to /

TOP_BUILD_DIR <path>

Overrides the top build directory path used to derive the pc_top_builddir package variable.

When this option is not provided, the default top build directory path is the first available of the following values:

1. CMAKE_PKG_CONFIG_TOP_BUILD_DIR

2. The PKG_CONFIG_TOP_BUILD_DIR environment variable

3. If no top build directory path is available, the pc_top_builddir package variable is not set

PREFIX <name>

Specifying a prefix creates an independent collection of pkg-config targets separate from previously populated targets. This enables multiple version of a given package to co-exist, for example packages from different sysroots.

The default prefix is an empty string.

BIND_PC_REQUIRES <<name>=<target>>...

A list of <name>=<target> pairs, the name is a package name as it appears in the Requires list of a pkg-config file and the target is a CMake-native target name (not a pkg-config target).

When a given package name appears in the Requires list of a package, it will be fulfilled with the associated CMake target. This behavior applies to all dependencies in the pkg-config graph that have not been previously populated.

Signatures

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

Added in version 3.31.

Extract the contents of the package into variables.

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

The following variables will be populated from the contents of package file:

Variable	Type	Definition
CMAKE_PKG_CONFIG_NAME	String	Value of the Name keyword
CMAKE_PKG_CONFIG_DESCRIPTION	String	Value of the Description keyword
CMAKE_PKG_CONFIG_VERSION	String	Value of the Version keyword
CMAKE_PKG_CONFIG_PROVIDES	List	Value of the Provides keyword
CMAKE_PKG_CONFIG_REQUIRES	List	Value of the Requires keyword
CMAKE_PKG_CONFIG_CONFLICTS	List	Value of the Conflicts keyword
CMAKE_PKG_CONFIG_CFLAGS	String	Value of the CFlags / Cflags keyword
CMAKE_PKG_CONFIG_INCLUDES	List	All -I prefixed flags from CMAKE_PKG_CONFIG_CFLAGS
CMAKE_PKG_CONFIG_COMPILE_OPTIONS	List	All flags not prefixed with -I from CMAKE_PKG_CONFIG_CFLAGS
CMAKE_PKG_CONFIG_LIBS	String	Value of the Libs keyword
CMAKE_PKG_CONFIG_LIBDIRS	List	All -L prefixed flags from CMAKE_PKG_CONFIG_LIBS
CMAKE_PKG_CONFIG_LIBNAMES	List	All -l prefixed flags from CMAKE_PKG_CONFIG_LIBS
CMAKE_PKG_CONFIG_LINK_OPTIONS	List	All flags not prefixed with -L or -l from CMAKE_PKG_CONFIG_LIBS
CMAKE_PKG_CONFIG_*_PRIVATE	*	CFLAGS / LIBS / REQUIRES and derived, but in their .private suffix forms

SYSTEM_INCLUDE_DIRS

Overrides the "system" directories for the purpose of flag mangling include directories in CMAKE_PKG_CONFIG_CFLAGS and derived variables.

When this option is not provided, the default directories are provided by the first available of the following values:

1. CMAKE_PKG_CONFIG_SYS_INCLUDE_DIRS

2. The PKG_CONFIG_SYSTEM_INCLUDE_PATH environment variable

3. The output of pkgconf --variable pc_system_includedirs pkg-config

4. A platform-dependent default value

Additionally, when the ENV_MODE is PKGCONF the CMAKE_PKG_CONFIG_PKGCONF_INCLUDES variable will be concatenated to the list if available. If it is not available, the following environment variables will be queried and concatenated:

• CPATH

• C_INCLUDE_PATH

• CPLUS_INCLUDE_PATH

• OBJC_INCLUDE_PATH

• INCLUDE (Windows Only)

SYSTEM_LIBRARY_DIRS

Overrides the "system" directories for the purpose of flag mangling library directories in CMAKE_PKG_CONFIG_LIBS and derived variables.

When this option is not provided, the default directories are provided by the first available of the following values:

1. CMAKE_PKG_CONFIG_SYS_LIB_DIRS

2. The PKG_CONFIG_SYSTEM_LIBRARY_PATH environment variable

3. The output of pkgconf --variable pc_system_libdirs pkg-config

4. A platform-dependent default value

Additionally, when the ENV_MODE is PKGCONF the CMAKE_PKG_CONFIG_PKGCONF_LIB_DIRS variable will be concatenated to the list if available. If it is not available, the LIBRARY_PATH environment variable will be queried and concatenated.

ALLOW_SYSTEM_INCLUDES

Preserves "system" directories during flag mangling of include directories in CMAKE_PKG_CONFIG_CFLAGS and derived variables.

When this option is not provided, the default value is determined by the first available of the following values:

1. CMAKE_PKG_CONFIG_ALLOW_SYS_INCLUDES

2. If the PKG_CONFIG_ALLOW_SYSTEM_CFLAGS environment variable is defined the flags are preserved, otherwise they are filtered during flag mangling.

ALLOW_SYSTEM_LIBS

Preserves "system" directories during flag mangling of library directories in CMAKE_PKG_CONFIG_LIBS and derived variables.

When this option is not provided, the default value is determined by the first available of the following values:

1. CMAKE_PKG_CONFIG_ALLOW_SYS_LIBS

2. If the PKG_CONFIG_ALLOW_SYSTEM_LIBS environment variable is defined the flags are preserved, otherwise they are filtered during flag mangling.

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

Added in version 4.1.

Populate a package in the pkg-config target namespace

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 enables manual control of resolution of a given package's Requires list without importing onto a native CMake target. Once populated, a package and its dependencies will be used for resolution of all future POPULATE and IMPORT commands.

A PKGCONFIG_<package>_FOUND variable will be set to indicate whether the package was found.

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

Added in version 4.1.

Import a pkg-config target as a CMake IMPORTED target

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

Creates a native CMake IMPORTED target that can be linked to via target_link_libraries(). This new target is named PkgConfig::<package> by default.

A PKGCONFIG_<package>_FOUND variable will be set to indicate whether the package was found.

NAME

Overrides the name of the created CMake target to PkgConfig::<name>. This does not affect the PKGCONFIG_<package>_FOUND variable.