Autotools (1)

1. File Format of *.pc Files

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. Keywords instead are pre-defined and are used by the commands available as part of pkg-config itself.

Name

    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.
Version

    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.
Requires, Conflicts

    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 >=.
Cflags, Libs

    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”.
Requires.private, Libs.private

    More specific details about the dependencies of a module, see Section 2.1, “Static linking”.
Description, URL

    Brief information about the package, mostly self-explaining.

1.1. Search paths

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 4, “Supporting Cross-Compilation”.
1.2. Include and library paths

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.

2. Dependencies

The pkg-config file format provides two main interfaces to declare dependencies between libraries (and other project using these files), as described in Section 1, “File Format of *.pc Files”: the Requires definitions and the Libs definition. Both of them also provide a .private variant. While this might sound redundant, their use is different enough to warrant their presence.

The Requires definition allows to import dependency information directly from another .pc data file, including compiler flags (Cflags), libraries, and its own set of required libraries.

The Libs definition instead only lists libraries, without inspecting their dependencies; this should usually be used for libraries that do not provide a .pc file, such as system libraries.

The reason why two sets of definitions are present has to be found in the way the link editors work in the UNIX world (Windows and Mac OS X are different worlds), and in particular in the world of ELF: shared libraries carry internally the list of their dependencies, but static libraries (archives) do not. This means that if you're linking statically to something, you need to provide its dependencies explicitly.

The decision on where to list a given dependency should follow a semantic approach: does the current library augment the dependency, or wrap around it? If the consumers of the current library still need to use interfaces from the former, the dependency should be visible directly to the consumers, so declare it as Requires or Libs. If, on the other hand, the dependency's interface is wrapper and hidden from the consumers, it should be declared in Requires.private or Libs.private.
2.1. Static linking

When using the private definitions for dependencies, the behaviour of pkg-config will change depending on whether it's targeting dynamic or static linking. In the former case, private dependencies will not be listed in the output, as they are not exposed to the consumer directly, and shared libraries will handle them.

Contrarily, when the link is static, it'll expand (recursively) all the private dependencies so that all the libraries are brought in. This is once again needed because of the way UNIX link editors work, as archives do not list their own dependencies directly. While libtool actually provides a wrapper around these archives, they are getting less and less common, so relying on them is not a good idea.

Unfortunately, at least as of February 2013, there is no easy way to tell at once to an Autotools-based build system that you intend to link statically; this means that the most common way to signal this to pkg-config becomes the command ./configure LDFLAGS="-static" PKG_CONFIG="pkg-config --static".