cmake_pkg_config¶
New in version 3.31.
Process pkg-config format package files.
Synopsis¶
cmake_pkg_config(EXTRACT <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.
There are multiple signatures for this command, and some of the options are common between them. They are:
EXACT/QUIET/REQUIREDThe
EXACToption 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
QUIEToption disables informational messages, including those indicating that the package cannot be found if it is notREQUIRED. TheREQUIREDoption 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 asPERMISSIVEwith 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_MODESpecifies which environment variables will be queried when running a given command. Possible modes are:
FDO: Queries only the original set ofPKG_CONFIG_*environment variables used by the freedesktop.orgpkg-configimplementation.PKGCONF: Queries the more extensive set of environment variables used by thepkgconfimplementation.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 asPKG_CONFIG_ALLOW_*, this means they are evaluated as truthy.PKG_CONFIG_SYSROOT_PATHis a minor exception. WhenENV_MODE IGNOREis used, no root path prepending will occur by default andpc_sysrootdirremains 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_pathpackage variable.When this option is not provided, the default library directory is the first available of the following values:
CMAKE_PKG_CONFIG_PC_LIB_DIRSThe
PKG_CONFIG_LIBDIRenvironment variableThe output of
pkg-config --variable pc_path pkg-configA 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_pathpackage variable.When this option is not provided, the default paths are the first available of the following values:
CMAKE_PKG_CONFIG_PC_PATHThe
PKG_CONFIG_PATHenvironment variableEmpty 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_UNINSTALLEDis 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:
CMAKE_PKG_CONFIG_DISABLE_UNINSTALLEDIf the
PKG_CONFIG_DISABLE_UNINSTALLEDenvironment 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
-Icompile flags and-Llibrary search locations; also used to derive thepc_sysrootdirpackage variable.When this option is not provided, the default root path is provided by the first available of the following values:
CMAKE_PKG_CONFIG_SYSROOT_DIRThe
PKG_CONFIG_SYSROOT_DIRenvironment variableIf no root path is available, nothing will be prepended to include or library directory paths and
pc_sysrootdirwill be set to/
TOP_BUILD_DIR <path>Overrides the top build directory path used to derived the
pc_top_builddirpackage variable.When this option is not provided, the default top build directory path is the first available of the following values:
CMAKE_PKG_CONFIG_TOP_BUILD_DIRThe
PKG_CONFIG_TOP_BUILD_DIRenvironment variableIf no top build directory path is available, the
pc_top_builddirpackage variable is not set
Signatures¶
- cmake_pkg_config(EXTRACT <package> [<version>] [...])¶
Extract the contents of the package into variables.
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>])
The following variables will be populated from the contents of package file:
Variable |
Type |
Definition |
|---|---|---|
|
String |
Value of the |
|
String |
Value of the |
|
String |
Value of the |
|
List |
Value of the |
|
List |
Value of the |
|
List |
Value of the |
|
String |
Value of the |
|
List |
All |
|
List |
All flags not prefixed with |
|
String |
Value of the |
|
List |
All |
|
List |
All |
|
List |
All flags not prefixed with |
|
* |
|
SYSTEM_INCLUDE_DIRSOverrides the "system" directories for the purpose of flag mangling include directories in
CMAKE_PKG_CONFIG_CFLAGSand derived variables.When this option is not provided, the default directories are provided by the first available of the following values:
CMAKE_PKG_CONFIG_SYS_INCLUDE_DIRSThe
PKG_CONFIG_SYSTEM_INCLUDE_PATHenvironment variableThe output of
pkgconf --variable pc_system_includedirs pkg-configA platform-dependent default value
Additionally, when the
ENV_MODEisPKGCONFtheCMAKE_PKG_CONFIG_PKGCONF_INCLUDESvariable will be concatenated to the list if available. If it is not available, the following environment variables will be queried and concatenated:CPATHC_INCLUDE_PATHCPLUS_INCLUDE_PATHOBJC_INCLUDE_PATHINCLUDE(Windows Only)
SYSTEM_LIBRARY_DIRSOverrides the "system" directories for the purpose of flag mangling library directories in
CMAKE_PKG_CONFIG_LIBSand derived variables.When this option is not provided, the default directories are provided by the first available of the following values:
CMAKE_PKG_CONFIG_SYS_LIB_DIRSThe
PKG_CONFIG_SYSTEM_LIBRARY_PATHenvironment variableThe output of
pkgconf --variable pc_system_libdirs pkg-configA platform-dependent default value
Additionally, when the
ENV_MODEisPKGCONFtheCMAKE_PKG_CONFIG_PKGCONF_LIB_DIRSvariable will be concatenated to the list if available. If it is not available, theLIBRARY_PATHenvironment variable will be queried and concatenated.ALLOW_SYSTEM_INCLUDESPreserves "system" directories during flag mangling of include directories in
CMAKE_PKG_CONFIG_CFLAGSand derived variables.When this option is not provided, the default value is determined by the first available of the following values:
CMAKE_PKG_CONFIG_ALLOW_SYS_INCLUDESIf the
PKG_CONFIG_ALLOW_SYSTEM_CFLAGSenvironment variable is defined the flags are preserved, otherwise they are filtered during flag mangling.
ALLOW_SYSTEM_LIBSPreserves "system" directories during flag mangling of library directories in
CMAKE_PKG_CONFIG_LIBSand derived variables.When this option is not provided, the default value is determined by the first available of the following values:
CMAKE_PKG_CONFIG_ALLOW_SYS_LIBSIf the
PKG_CONFIG_ALLOW_SYSTEM_LIBSenvironment variable is defined the flags are preserved, otherwise they are filtered during flag mangling.