The heart of pkg-config lies in the data files that the various applications install. These data files are actually simple text files with some special syntax thrown in. They are neither INI-style configuration files, nor simple key-value pairs and are not even complete scripts.
The name of the file is the name of the module that can be tested with PKG_CHECK_MODULES
function. The content is simple text, which can be divided into variables definitions and
keyword declaration. Both are designed to be kept in a single line.
Variables can be used to define temporary values, but they can also provide arbitrary information to pkg-config users when needed (see Section 4, “Additional Variables”). Keywords instead are pre-defined and are used by the commands available as part of pkg-config itself.
Provides a human-readable name for the package; it does not have to be the same as the module name, that is instead decided based on the datafile's name.
Complete version of the package; it supports most of the sane version specifications. Please note that only a single data file for a module can be used so you might have to duplicate part of the version information in both the module name and this keyword.
These terms specify the dependencies of a module, with or without
version limitations. As the names of the terms indicate,
Requires lists the other modules that
need to be present, while Conflicts
lists the packages that cannot be
present when making use of the current module.
You cannot list the same module more than once in the
requirements, but you can list it as many time as you want
in the conflicts. All the modules can optionally have a
version specifier, and you can use the seven basic
comparisons as defined by the C language:
=, <,
>, <= and
>=.
The two fundamental specifications that the
pkg-config call will report to
its caller, such as the macro discussed in Section 3, “The PKG_CHECK_MODULES Macro”. They represent the
parameters to pass to the compiler and linker command-lines
to make use of the current module.
It's important not to list the entries related to further dependencies, since pkg-config will take care of running transitive dependency discovery, see also Section 2, “Dependencies”.
More specific details about the dependencies of a module, see Section 2.1, “Static linking”.
Brief information about the package, mostly self-explaining.
By default, pkg-config will search
for modules installing data files in two directories: one for
the architecture-specific modules, that is installed in a
sub-directory of the libdir (usually
/usr/lib/pkgconfig), and one for
non-architecture specific modules, that can be shared among
multiple architectures (usually
/usr/share/pkgconfig).
You can add further paths to its search by defining the PKG_CONFIG_PATH, or
you can replace the default search paths by setting the
PKG_CONFIG_LIBDIR. These tricks are often used to create wrappers to
pkg-config for cross-compilation. As described in Section 5, “Supporting Cross-Compilation”.
When providing the compiler and linker flags, you should always provide those to direct said
tool to the paths where the library and its headers are to be found (namely,
-I and -L, respectively). It is thus common practice to get
the configure script to substitute variables on a template file, and use
them to set the flags.
Example 4.1. Simple project's template file and configure.ac code.
The following code is a (snippet of) a template file that would then be named along the
lines of foo.pc.in:
prefix=@prefix@
exec_prefix=@exec_prefix@
libdir=@libdir@
includedir=@includedir@
[...]
Cflags: -I${includedir}
Libs: -L${libdir} -lfoo
In the configure.ac files you would have, toward the end:
AC_CONFIG_FILES([foo.pc]) AC_OUTPUT
In the template files this way, it's common to have, beside the obvious definition of
libdir and includedir, the definition for
prefix and exec_prefix. The reason for this, is that the
variables are defined by default, in autoconf-generated code, as
relative to another variable, like this:
prefix=/usr/local
exec_prefix=${prefix}
libdir=${prefix}/lib
includedir=${prefix}/include
These values require the user to only override the origin point (prefix)
and offsets all the other paths at the same time. Since pkg-config
has been designed to work in pair with the rest of the autotools stack, the same expansion
rules apply, making it easy to deal with, as long as the previously shown example is followed.
It is important to note that, when the paths are known to pkg-config as matching the system default search paths, they are not emitted in the output usage, to avoid contaminating the compile and link command lines with duplicate search paths that could slow it down considerably and, in some cases, cause cross-compiling wrappers to fail.