421 lines
17 KiB
HTML
421 lines
17 KiB
HTML
<!--
|
|
Copyright (C) 2010 Dan Nicholson.
|
|
|
|
This program is free software; you can redistribute it and/or modify it
|
|
under the terms of the GNU General Public License as published by the
|
|
Free Software Foundation; either version 2 of the License, or (at your
|
|
option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License along
|
|
with this program; if not, write to the Free Software Foundation, Inc.,
|
|
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
-->
|
|
|
|
<!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">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<style type="text/css">
|
|
pre { background-color: #f0f0f0; padding: 0.4cm; }
|
|
</style>
|
|
|
|
<title>Guide to pkg-config</title>
|
|
</head>
|
|
|
|
<body>
|
|
<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>
|
|
|
|
<pre>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</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
|
|
=, <, >, <= or >=.</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>
|
|
|
|
<pre>prefix=/usr/local
|
|
includedir=${prefix}/include
|
|
|
|
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>
|
|
|
|
<pre>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</pre>
|
|
|
|
<p>The version of the modules can be obtained with the <tt>--modversion</tt>
|
|
option.</p>
|
|
|
|
<pre>$ pkg-config --modversion foo
|
|
1.0.0
|
|
$ pkg-config --modversion bar
|
|
2.1.2</pre>
|
|
|
|
<p>To print the link flags needed for each module, use the <tt>--libs</tt>
|
|
option.</p>
|
|
|
|
<pre>$ pkg-config --libs foo
|
|
-lfoo
|
|
$ pkg-config --libs bar
|
|
-lbar</pre>
|
|
|
|
<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
|
|
-I/usr/include/foo
|
|
$ pkg-config --cflags --static bar
|
|
-I/usr/include/foo</pre>
|
|
|
|
<p>Another useful option, <tt>--exists</tt>, can be used to test for a
|
|
module's availability.</p>
|
|
|
|
<pre>$ pkg-config --exists foo
|
|
$ echo $?
|
|
0</pre>
|
|
|
|
<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
|
|
1.0.0</pre>
|
|
|
|
<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>
|
|
|
|
<li><b>PKG_CHECK_EXISTS(MODULES, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])</b>:
|
|
Checks to see whether a particular set of modules exists.</li>
|
|
|
|
<li><b>PKG_CHECK_MODULES(VARIABLE-PREFIX, MODULES, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])</b>:
|
|
Checks to see whether a particular set of modules exists. If so, it sets
|
|
<tt><VARIABLE-PREFIX>_CFLAGS</tt> and
|
|
<tt><VARIABLE-PREFIX>_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>
|
|
|
|
<pre>configure.ac:
|
|
PKG_CHECK_MODULES([X], [x])
|
|
|
|
Makefile.am:
|
|
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 <dbn.lists (at) gmail (dot) com></address>
|
|
|
|
<p>Copyright (C) 2010 Dan Nicholson.<br/>
|
|
This document is licensed under the
|
|
<a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt">GNU General Public License, Version 2</a>
|
|
or any later version.</p>
|
|
|
|
</body>
|
|
</html>
|