This document aims to give an overview to using the pkg-config tool from the perspective of both a user and a developer. It reviews the concepts behind pkg-config, how to write pkg-config files to support your project, and how to use pkg-config to integrate with 3rd party projects.
More information on pkg-config can be found at the website and in the pkg-config(1) manual page.
This document assumes usage of pkg-config on a Unix-like operating system such as Linux. Some of the details may be different on other platforms.
Modern computer systems use many layered components to provide applications to the user. One of the difficulties in assembling these parts is properly integrating them. pkg-config collects metadata about the installed libraries on the system and easily provides it to the user.
Without a metadata system such as pkg-config, it can be very difficult to locate and obtain details about the services provided on a given computer. For a developer, installing pkg-config files with your package greatly eases adoption of your API.
The primary use of pkg-config is to provide the necessary details for compiling and linking a program to a library. This metadata is stored in pkg-config files. These files have the suffix .pc and reside in specific locations known to the pkg-config tool. This will be described in more detail later.
The file format contains predefined metadata keywords and freeform variables. An example may be illustrative:
prefix=/usr/local
exec_prefix=${prefix}
includedir=${prefix}/include
libdir=${exec_prefix}/lib
Name: foo
Description: The foo library
Version: 1.0.0
Cflags: -I${includedir}/foo
Libs: -L${libdir} -lfoo
The keyword definitions such as Name: begin with a keyword followed by a colon and the value. The variables such as prefix= are a string and value separated by an equals sign. The keywords are defined and exported by pkg-config. The variables are not necessary, but can be used by the keyword definitions for flexibility or to store data not covered by pkg-config.
Here is a short description of the keyword fields. A more in depth description of these fields and how to use them effectively will be given in the Writing pkg-config files section.
When creating pkg-config files for a package, it is first necessary to decide how they will be distributed. Each file is best used to describe a single library, so each package should have at least as many pkg-config files as they do installed libraries.
The package name is determined through the filename of the pkg-config metadata file. This is the portion of the filename prior to the .pc suffix. A common choice is to match the library name to the .pc name. For instance, a package installing libfoo.so would have a corresponding libfoo.pc file containing the pkg-config metadata. This choice is not necessary; the .pc file should simply be a unique identifier for your library. Following the above example, foo.pc or foolib.pc would probably work just as well.
The Name, Description and URL fields are purely informational and should be easy to fill in. The Version field is a bit trickier to ensure that it is usable by consumers of the data. pkg-config uses the algorithm from RPM for version comparisons. This works best with a dotted decimal number such as 1.2.3 since letters can cause unexpected results. The number should be monotonically increasing and be as specific as possible in describing the library. Usually it's sufficient to use the package's version number here since it's easy for consumers to track.
Before describing the more useful fields, it will be helpful to demonstrate variable definitions. The most common usage is to define the installation paths so that they don't clutter the metadata fields. Since the variables are expanded recursively, this is very helpful when used in conjunction with autoconf derived paths.
prefix=/usr/local
includedir=${prefix}/include
Cflags: -I${includedir}/foo
The most important pkg-config metadata fields are Requires, Requires.private, Cflags, Libs and Libs.private. They will define the metadata used by external projects to compile and link with the library.
Requires and Requires.private define other modules needed by the library. It is usually preferred to use the private variant of Requires to avoid exposing unnecessary libraries to the program that is linking with your library. If the program will not be using the symbols of the required library, it should not be linking directly to that library. See the discussion of overlinking for a more thorough explanation.
Since pkg-config always exposes the link flags of the Requires libraries, these modules will become direct dependencies of the program. On the other hand, libraries from Requires.private will only be included when static linking. For this reason, it is usually only appropriate to add modules from the same package in Requires.
The Libs field contains the link flags necessary to use that library. In addition, Libs and Libs.private contain link flags for other libraries not supported by pkg-config. Similar to the Requires field, it is preferred to add link flags for external libraries to the Libs.private field so programs do not acquire an additional direct dependency.
Finally, the Cflags contains the compiler flags for using the library. Unlike the Libs field, there is not a private variant of Cflags. This is because the data types and macro definitions are needed regardless of the linking scenario.
Assuming that there are .pc files installed on the system, the pkg-config tool is used to extract the metadata for usage. A short description of the options can be seen by executing pkg-config --help. A more in depth discussion can be found in the pkg-config(1) manual page. This section will provide a brief explanation of common usages.
Consider a system with two modules, foo and bar. Their .pc files might look like this:
foo.pc:
prefix=/usr
exec_prefix=${prefix}
includedir=${prefix}/include
libdir=${exec_prefix}/lib
Name: foo
Description: The foo library
Version: 1.0.0
Cflags: -I${includedir}/foo
Libs: -L${libdir} -lfoo
bar.pc:
prefix=/usr
exec_prefix=${prefix}
includedir=${prefix}/include
libdir=${exec_prefix}/lib
Name: bar
Description: The bar library
Version: 2.1.2
Requires.private: foo >= 0.7
Cflags: -I${includedir}
Libs: -L${libdir} -lbar
The version of the modules can be obtained with the --modversion option.
$ pkg-config --modversion foo 1.0.0 $ pkg-config --modversion bar 2.1.2
To print the link flags needed for each module, use the --libs option.
$ pkg-config --libs foo -lfoo $ pkg-config --libs bar -lbar
Notice that pkg-config has suppressed part of the Libs field for both modules. This is because it treats the -L flag specially and knows that the ${libdir} directory /usr/lib is part of the system linker search path. This keeps pkg-config from interfering with the linker operation.
Also, although foo is required by bar, the link flags for foo are not output. This is because foo is not directly needed by an application that only wants to use the bar library. For statically linking a bar application, we need both sets of linker flags:
$ pkg-config --libs --static bar -lbar -lfoo
pkg-config needs to output both sets of link flags in this case to ensure that the statically linked application will find all the necessary symbols. On the other hand, it will always output all the Cflags.
$ pkg-config --cflags bar -I/usr/include/foo $ pkg-config --cflags --static bar -I/usr/include/foo
Another useful option, --exists, can be used to test for a module's availability.
$ pkg-config --exists foo $ echo $? 0
One of the nicest features of pkg-config is providing version checking. It can be used to determine if a sufficient version is available.
$ pkg-config --libs "bar >= 2.7" Requested 'bar >= 2.7' but version of bar is 2.1.2
Some commands will provide more verbose output when combined with the --print-errors option.
$ pkg-config --exists --print-errors xoxo Package xoxo was not found in the pkg-config search path. Perhaps you should add the directory containing `xoxo.pc' to the PKG_CONFIG_PATH environment variable No package 'xoxo' found
The message above references the PKG_CONFIG_PATH environment variable. This variable is used to augment pkg-config's search path. On a typical Unix system, it will search in the directories /usr/lib/pkgconfig and /usr/share/pkgconfig. This will usually cover system installed modules. However, some local modules may be installed in a different prefix such as /usr/local. In that case, it's necessary to prepend the search path so that pkg-config can locate the .pc files.
$ pkg-config --modversion hello Package hello was not found in the pkg-config search path. Perhaps you should add the directory containing `hello.pc' to the PKG_CONFIG_PATH environment variable No package 'hello' found $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig $ pkg-config --modversion hello 1.0.0
A few autoconf macros are also provided to ease integration of pkg-config modules into projects.
The pkg-config output can easily be used on the compiler command line. Assuming the x library has a x.pc pkg-config file:
cc `pkg-config --cflags --libs x` -o myapp myapp.c
The integration can be more robust when used with autoconf and automake. By using the supplied PKG_CHECK_MODULES macro, the metadata is easily accessed in the build process.
configure.ac: PKG_CHECK_MODULES([X], [x]) Makefile.am: myapp_CFLAGS = $(X_CFLAGS) myapp_LDADD = $(X_LIBS)
If the x module is found, the macro will fill and substitute the X_CFLAGS and X_LIBS variables. If the module is not found, an error will be produced. Optional 3rd and 4th arguments can be supplied to PKG_CHECK_MODULES to control actions when the module is found or not.
If the x library has pkg-config support, add it to the Requires.private field. If it does not, augment the Cflags field with the necessary compiler flags for using the libx headers. In either case, pkg-config will output the compiler flags when --static is used or not.
Again, add the module to Requires.private if it supports pkg-config. In this case, the compiler flags will be emitted unnecessarily, but it ensures that the linker flags will be present when linking statically. If libx does not support pkg-config, add the necessary linker flags to Libs.private.
Copyright (C) 2010 Dan Nicholson.
This document is licensed under the
GNU General Public License, Version 2
or any later version.