[PATCH] Guide to pkg-config

Dan Nicholson dbn.lists at gmail.com
Mon Feb 9 22:42:58 PST 2009

I took a stab at writing a guide to pkg-config both for developers and
users. It's sort of a braindump, and I can't decide if it's too detailed
or not detailed enough. I'm posting it here, though, for comments. You
can read it online here:


The FAQs come from Matthias'. I'd be happy to fix up any errors or edits
people see necessary. Some of the content duplicates pkg-config(1). I
didn't see how to avoid that, though.

If there's interest, I could convert to DocBook, but I think this is a
starting point. Patch is inline below.


=== modified file 'Makefile.am'
--- old/Makefile.am	2007-12-29 13:40:41 +0000
+++ new/Makefile.am	2009-02-10 06:20:26 +0000
@@ -11,6 +11,8 @@
 m4dir = $(datadir)/aclocal
 m4_DATA = pkg.m4
+dist_doc_DATA = guide.html
 man_MANS = pkg-config.1
 EXTRA_DIST = $(m4_DATA) $(man_MANS) README.win32

=== added file 'guide.html'
--- old/guide.html	1970-01-01 00:00:00 +0000
+++ new/guide.html	2009-02-10 06:18:17 +0000
@@ -0,0 +1,417 @@
+Copyright (c)  2009  Dan Nicholson.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+A copy of the license is included in the section entitled "GNU
+Free Documentation License".
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <style type="text/css">
+    pre { background-color: #f0f0f0; padding: 0.4cm; }
+    <!--
+    .green { color: #003300; }
+    .blue  { color: #0000CC; }
+    .maroon { color: maroon; }
+    -->
+  </style>
+  <title>Guide to pkg-config</title>
+  <h1><a name="top">Guide to pkg-config</a></h1>
+  <h3>Dan Nicholson</h3>
+  <ul>
+    <li><a href="#overview">Overview</a></li>
+    <li><a href="#why">Why?</a></li>
+    <li><a href="#concepts">Concepts</a></li>
+    <li><a href="#writing">Writing pkg-config files</a></li>
+    <li><a href="#using">Using pkg-config files</a></li>
+    <!--<li><a href="#examples">Examples</a></li>-->
+    <li><a href="#faq">Frequently asked questions</a></li>
+  </ul>
+  <h2><a name="overview">Overview</a></h2>
+  <p>This document aims to give an overview to using the <tt>pkg-config</tt>
+  tool from the perspective of both a user and a developer. It reviews the
+  concepts behind <tt>pkg-config</tt>, how to write <tt>pkg-config</tt> files
+  to support your project, and how to use <tt>pkg-config</tt> to integrate
+  with 3rd party projects.</p>
+  <p>More information on <tt>pkg-config</tt> can be found at the
+  <a href="http://pkg-config.freedesktop.org/">website</a> and in the
+  <tt>pkg-config(1)</tt> manual page.</p>
+  <p>This document assumes usage of <tt>pkg-config</tt> on a Unix-like
+  operating system such as Linux. Some of the details may be different on
+  other platforms.</p>
+  <h2><a name="why">Why?</a></h2>
+  <p>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. <tt>pkg-config</tt> collects metadata about
+  the installed libraries on the system and easily provides it to the user.
+  </p>
+  <p>Without a metadata system such as <tt>pkg-config</tt>, it can be very
+  difficult to locate and obtain details about the services provided on a
+  given computer. For a developer, installing <tt>pkg-config</tt> files with
+  your package greatly eases adoption of your API.</p>
+  <h2><a name="concepts">Concepts</a></h2>
+  <p>The primary use of <tt>pkg-config</tt> is to provide the necessary
+  details for compiling and linking a program to a library. This metadata is
+  stored in <tt>pkg-config</tt> files. These files have the suffix
+  <tt>.pc</tt> and reside in specific locations known to the
+  <tt>pkg-config</tt> tool. This will be described in more detail later.</p>
+  <p>The file format contains predefined metadata keywords and freeform
+  variables. An example may be illustrative:<p>
+Name: foo
+Description: The foo library
+Version: 1.0.0
+Cflags: -I${includedir}/foo
+Libs: -L${libdir} -lfoo</pre>
+  <p>The keyword definitions such as <tt>Name:</tt> begin with a keyword
+  followed by a colon and the value. The variables such as <tt>prefix=</tt>
+  are a string and value separated by an equals sign. The keywords are defined
+  and exported by <tt>pkg-config</tt>. The variables are not necessary, but
+  can be used by the keyword definitions for flexibility or to store data not
+  covered by <tt>pkg-config</tt>.</p>
+  <p>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 <a href="#writing">Writing pkg-config files</a> section.</p>
+  <ul>
+    <li><b>Name</b>: A human-readable name for the library or package. This
+    does not affect usage of the <tt>pkg-config</tt> tool, which uses the name
+    of the <tt>.pc</tt> file.</li>
+    <li><b>Description</b>: A brief description of the package.</li>
+    <li><b>URL</b>: An URL where people can get more information about and
+    download the package.</li>
+    <li><b>Version</b>: A string specifically defining the version of the
+    package.</li>
+    <li><b>Requires</b>: A list of packages required by this package. The
+    versions of these packages may be specified using the comparison operators
+    =, &lt;, &gt;, &lt;= or &gt;=.</li>
+    <li><b>Requires.private</b>: A list of private packages required by this
+    package but not exposed to applications. The version specific rules from
+    the <tt>Requires</tt> field also apply here.</li>
+    <li><b>Conflicts</b>: An optional field describing packages that this one
+    conflicts with. The version specific rules from the <tt>Requires</tt>
+    field also apply here. This field also takes multiple instances of the
+    same package. E.g., <tt>Conflicts: bar < 1.2.3, bar >= 1.3.0</tt>.</li>
+    <li><b>Cflags</b>: The compiler flags specific to this package and any
+    required libraries that don't support <tt>pkg-config</tt>. If the required
+    libraries support <tt>pkg-config</tt>, they should be added to
+    <tt>Requires</tt> or <tt>Requires.private</tt>.</li>
+    <li><b>Libs</b>: The link flags specific to this package and any required
+    libraries that don't support <tt>pkg-config</tt>. The same rule as
+    <tt>Cflags</tt> applies here.</li>
+    <li><b>Libs.private</b>: The link flags for private libraries required by
+    this package but not exposed to applications. The same rule as
+    <tt>Cflags</tt> applies here.</li>
+  </ul>
+  <h2><a name="writing">Writing pkg-config files</a></h2>
+  <p>When creating <tt>pkg-config</tt> 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
+  <tt>pkg-config</tt> files as they do installed libraries.</p>
+  <p>The package name is determined through the filename of the
+  <tt>pkg-config</tt> metadata file. This is the portion of the filename prior
+  to the <tt>.pc</tt> suffix. A common choice is to match the library name to
+  the <tt>.pc</tt> name. For instance, a package installing <tt>libfoo.so</tt>
+  would have a corresponding <tt>libfoo.pc</tt> file containing the
+  <tt>pkg-config</tt> metadata. This choice is not necessary; the <tt>.pc</tt>
+  file should simply be a unique identifier for your library. Following the
+  above example, <tt>foo.pc</tt> or <tt>foolib.pc</tt> would probably work
+  just as well.</p>
+  <p>The <tt>Name</tt>, <tt>Description</tt> and <tt>URL</tt> fields are
+  purely informational and should be easy to fill in. The <tt>Version</tt>
+  field is a bit trickier to ensure that it is usable by consumers of the
+  data. <tt>pkg-config</tt> uses the algorithm from
+  <a href="http://rpm.org/">RPM</a> for version comparisons. This works best
+  with a dotted decimal number such as <tt>1.2.3</tt> 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.</p>
+  <p>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.</p>
+Cflags: -I${includedir}/foo</pre>
+  <p>The most important <tt>pkg-config</tt> metadata fields are
+  <tt>Requires</tt>, <tt>Requires.private</tt>, <tt>Cflags</tt>, <tt>Libs</tt>
+  and <tt>Libs.private</tt>. They will define the metadata used by external
+  projects to compile and link with the library.</p>
+  <p><tt>Requires</tt> and <tt>Requires.private</tt> define other modules
+  needed by the library. It is usually preferred to use the private variant of
+  <tt>Requires</tt> 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
+  <a href="http://wiki.mandriva.com/en/Overlinking">overlinking</a> for a more
+  thorough explanation.</p>
+  <p>Since <tt>pkg-config</tt> always exposes the link flags of the
+  <tt>Requires</tt> libraries, these modules will become direct dependencies
+  of the program. On the other hand, libraries from <tt>Requires.private</tt>
+  will only be included when static linking. For this reason, it is usually
+  only appropriate to add modules from the same package in <tt>Requires</tt>.
+  </p>
+  <p>The <tt>Libs</tt> field contains the link flags necessary to use that
+  library. In addition, <tt>Libs</tt> and <tt>Libs.private</tt> contain link
+  flags for other libraries not supported by <tt>pkg-config</tt>. Similar to
+  the <tt>Requires</tt> field, it is preferred to add link flags for external
+  libraries to the <tt>Libs.private</tt> field so programs do not acquire an
+  additional direct dependency.</p>
+  <p>Finally, the <tt>Cflags</tt> contains the compiler flags for using the
+  library. Unlike the <tt>Libs</tt> field, there is not a private variant of
+  <tt>Cflags</tt>. This is because the data types and macro definitions are
+  needed regardless of the linking scenario.</p>
+  <h2><a name="using">Using pkg-config files</a></h2>
+  <p>Assuming that there are <tt>.pc</tt> files installed on the system, the
+  <tt>pkg-config</tt> tool is used to extract the metadata for usage. A short
+  description of the options can be seen by executing
+  <tt>pkg-config --help</tt>. A more in depth discussion can be found in the
+  <tt>pkg-config(1)</tt> manual page. This section will provide a brief
+  explanation of common usages.</tt>
+  <p>Consider a system with two modules, <tt>foo</tt> and <tt>bar</tt>.
+  Their <tt>.pc</tt> files might look like this:</p>
+Name: foo
+Description: The foo library
+Version: 1.0.0
+Cflags: -I${includedir}/foo
+Libs: -L${libdir} -lfoo
+Name: bar
+Description: The bar library
+Version: 2.1.2
+Requires.private: foo >= 0.7
+Cflags: -I${includedir}
+Libs: -L${libdir} -lbar</pre>
+  <p>The version of the modules can be obtained with the <tt>--modversion</tt>
+  option.</p>
+<pre>$ pkg-config --modversion foo
+$ pkg-config --modversion bar
+  <p>To print the link flags needed for each module, use the <tt>--libs</tt>
+  option.</p>
+<pre>$ pkg-config --libs foo
+$ pkg-config --libs bar
+  <p>Notice that <tt>pkg-config</tt> has suppressed part of the <tt>Libs</tt>
+  field for both modules. This is because it treats the <tt>-L</tt> flag
+  specially and knows that the <tt>${libdir}</tt> directory <tt>/usr/lib</tt>
+  is part of the system linker search path. This keeps <tt>pkg-config</tt>
+  from interfering with the linker operation.</p>
+  <p>Also, although <tt>foo</tt> is required by <tt>bar</tt>, the link flags
+  for <tt>foo</tt> are not output. This is because <tt>foo</tt> is not
+  directly needed by an application that only wants to use the <tt>bar</tt>
+  library. For statically linking a <tt>bar</tt> application, we need both
+  sets of linker flags:</p>
+<pre>$ pkg-config --libs --static bar
+-lbar -lfoo</pre>
+  <p><tt>pkg-config</tt> 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 <tt>Cflags</tt>.
+  </p>
+<pre>$ pkg-config --cflags bar
+$ pkg-config --cflags --static bar
+  <p>Another useful option, <tt>--exists</tt>, can be used to test for a
+  module's availability.</p>
+<pre>$ pkg-config --exists foo
+$ echo $?
+  <p>One of the nicest features of <tt>pkg-config</tt> is providing version
+  checking. It can be used to determine if a sufficient version is available.
+  </p>
+<pre>$ pkg-config --libs "bar >= 2.7"
+Requested 'bar >= 2.7' but version of bar is 2.1.2</pre>
+  <p>Some commands will provide more verbose output when combined with the
+  <tt>--print-errors</tt> option.</p>
+<pre>$ 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</pre>
+  <p>The message above references the <tt>PKG_CONFIG_PATH</tt> environment
+  variable. This variable is used to augment <tt>pkg-config</tt>'s search
+  path. On a typical Unix system, it will search in the directories
+  <tt>/usr/lib/pkgconfig</tt> and <tt>/usr/share/pkgconfig</tt>. This will
+  usually cover system installed modules. However, some local modules may be
+  installed in a different prefix such as <tt>/usr/local</tt>. In that case,
+  it's necessary to prepend the search path so that <tt>pkg-config</tt> can
+  locate the <tt>.pc</tt> files.</p>
+<pre>$ 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
+  <p>A few <a href="http://www.gnu.org/software/autoconf/">autoconf</a> macros
+  are also provided to ease integration of <tt>pkg-config</tt> modules into
+  projects.</p>
+  <ul>
+    <li><b>PKG_PROG_PKG_CONFIG([MIN-VERSION])</b>: Locates the
+    <tt>pkg-config</tt> tool on the system and checks the version for
+    compatibility.</li>
+    Checks to see whether a particular set of modules exists.</li>
+    Checks to see whether a particular set of modules exists. If so, it sets
+    <tt>&lt;VARIABLE-PREFIX&gt;_CFLAGS</tt> and
+    <tt>&lt;VARIABLE-PREFIX&gt;_LIBS</tt> according to the output from
+    <tt>pkg-config --cflags</tt> and <tt>pkg-config --libs</tt>.</li>
+  </ul>
+  <!--<h2><a name="examples">Examples</a></h2>-->
+  <h2><a name="faq">Frequently asked questions</a></h2>
+  <ol>
+    <li>My program uses library <tt>x</tt>. What do I do?</li>
+    <p>The <tt>pkg-config</tt> output can easily be used on the compiler
+    command line. Assuming the <tt>x</tt> library has a <tt>x.pc</tt>
+    <tt>pkg-config</tt> file:</p>
+<pre>cc `pkg-config --cflags --libs x` -o myapp myapp.c</pre>
+    <p>The integration can be more robust when used with
+    <a href="http://www.gnu.org/software/autoconf/">autoconf</a> and
+    <a href="http://www.gnu.org/software/automake/">automake</a>. By using the
+    supplied <tt>PKG_CHECK_MODULES</tt> macro, the metadata is easily accessed
+    in the build process.</p>
+myapp_CFLAGS = $(X_CFLAGS)
+myapp_LDADD = $(X_LIBS)</pre>
+    <p>If the <tt>x</tt> module is found, the macro will fill and substitute
+    the <tt>X_CFLAGS</tt> and <tt>X_LIBS</tt> variables. If the module is not
+    found, an error will be produced. Optional 3rd and 4th arguments can be
+    supplied to <tt>PKG_CHECK_MODULES</tt> to control actions when the module
+    is found or not.</p>
+    <li>My library <tt>z</tt> installs header files which include <tt>libx</tt>
+    headers. What do I put in my <tt>z.pc</tt> file?</li>
+    <p>If the <tt>x</tt> library has <tt>pkg-config</tt> support, add it to
+    the <tt>Requires.private</tt> field. If it does not, augment the
+    <tt>Cflags</tt> field with the necessary compiler flags for using the
+    <tt>libx</tt> headers. In either case, <tt>pkg-config</tt> will output
+    the compiler flags when <tt>--static</tt> is used or not.</p>
+    <li>My library <tt>z</tt> uses <tt>libx</tt> internally, but does not
+    expose <tt>libx</tt> data types in its public API. What do I put in my
+    <tt>z.pc</tt> file?</li>
+    <p>Again, add the module to <tt>Requires.private</tt> if it supports
+    <tt>pkg-config</tt>. In this case, the compiler flags will be emitted
+    unnecessarily, but it ensures that the linker flags will be present when
+    linking statically. If <tt>libx</tt> does not support <tt>pkg-config</tt>,
+    add the necessary linker flags to <tt>Libs.private</tt>.</p>
+  </ol>
+  <hr/>
+  <address>Dan Nicholson &lt;dbn.lists (at) gmail (dot) com&gt;</address>
+  <p>Copyright (c)  2009  Dan Nicholson.<br/>
+  This document is licensed under the
+  <a href="http://www.gnu.org/licenses/fdl-1.3-standalone.html">GNU Free Documentation License, Version 1.3</a>
+  or any later version.</p>

More information about the pkg-config mailing list