2 Copyright (C) 2010 Dan Nicholson.
4 This program is free software; you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by the
6 Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
9 This program is distributed in the hope that it will be useful, but
10 WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 General Public License for more details.
14 You should have received a copy of the GNU General Public License along
15 with this program; if not, write to the Free Software Foundation, Inc.,
16 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
20 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
22 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
24 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
25 <style type="text/css">
26 pre { background-color: #f0f0f0; padding: 0.4cm; }
29 <title>Guide to pkg-config</title>
33 <h1><a name="top">Guide to pkg-config</a></h1>
35 <h3>Dan Nicholson</h3>
38 <li><a href="#overview">Overview</a></li>
39 <li><a href="#why">Why?</a></li>
40 <li><a href="#concepts">Concepts</a></li>
41 <li><a href="#writing">Writing pkg-config files</a></li>
42 <li><a href="#using">Using pkg-config files</a></li>
43 <!--<li><a href="#examples">Examples</a></li>-->
44 <li><a href="#faq">Frequently asked questions</a></li>
47 <h2><a name="overview">Overview</a></h2>
49 <p>This document aims to give an overview to using the <tt>pkg-config</tt>
50 tool from the perspective of both a user and a developer. It reviews the
51 concepts behind <tt>pkg-config</tt>, how to write <tt>pkg-config</tt> files
52 to support your project, and how to use <tt>pkg-config</tt> to integrate
53 with 3rd party projects.</p>
55 <p>More information on <tt>pkg-config</tt> can be found at the
56 <a href="http://pkg-config.freedesktop.org/">website</a> and in the
57 <tt>pkg-config(1)</tt> manual page.</p>
59 <p>This document assumes usage of <tt>pkg-config</tt> on a Unix-like
60 operating system such as Linux. Some of the details may be different on
63 <h2><a name="why">Why?</a></h2>
65 <p>Modern computer systems use many layered components to provide
66 applications to the user. One of the difficulties in assembling these parts
67 is properly integrating them. <tt>pkg-config</tt> collects metadata about
68 the installed libraries on the system and easily provides it to the user.
71 <p>Without a metadata system such as <tt>pkg-config</tt>, it can be very
72 difficult to locate and obtain details about the services provided on a
73 given computer. For a developer, installing <tt>pkg-config</tt> files with
74 your package greatly eases adoption of your API.</p>
76 <h2><a name="concepts">Concepts</a></h2>
78 <p>The primary use of <tt>pkg-config</tt> is to provide the necessary
79 details for compiling and linking a program to a library. This metadata is
80 stored in <tt>pkg-config</tt> files. These files have the suffix
81 <tt>.pc</tt> and reside in specific locations known to the
82 <tt>pkg-config</tt> tool. This will be described in more detail later.</p>
84 <p>The file format contains predefined metadata keywords and freeform
85 variables. An example may be illustrative:<p>
87 <pre>prefix=/usr/local
89 includedir=${prefix}/include
90 libdir=${exec_prefix}/lib
93 Description: The foo library
95 Cflags: -I${includedir}/foo
96 Libs: -L${libdir} -lfoo</pre>
98 <p>The keyword definitions such as <tt>Name:</tt> begin with a keyword
99 followed by a colon and the value. The variables such as <tt>prefix=</tt>
100 are a string and value separated by an equals sign. The keywords are defined
101 and exported by <tt>pkg-config</tt>. The variables are not necessary, but
102 can be used by the keyword definitions for flexibility or to store data not
103 covered by <tt>pkg-config</tt>.</p>
105 <p>Here is a short description of the keyword fields. A more in depth
106 description of these fields and how to use them effectively will be given in
107 the <a href="#writing">Writing pkg-config files</a> section.</p>
110 <li><b>Name</b>: A human-readable name for the library or package. This
111 does not affect usage of the <tt>pkg-config</tt> tool, which uses the name
112 of the <tt>.pc</tt> file.</li>
114 <li><b>Description</b>: A brief description of the package.</li>
116 <li><b>URL</b>: An URL where people can get more information about and
117 download the package.</li>
119 <li><b>Version</b>: A string specifically defining the version of the
122 <li><b>Requires</b>: A list of packages required by this package. The
123 versions of these packages may be specified using the comparison operators
124 =, <, >, <= or >=.</li>
126 <li><b>Requires.private</b>: A list of private packages required by this
127 package but not exposed to applications. The version specific rules from
128 the <tt>Requires</tt> field also apply here.</li>
130 <li><b>Conflicts</b>: An optional field describing packages that this one
131 conflicts with. The version specific rules from the <tt>Requires</tt>
132 field also apply here. This field also takes multiple instances of the
133 same package. E.g., <tt>Conflicts: bar < 1.2.3, bar >= 1.3.0</tt>.</li>
135 <li><b>Cflags</b>: The compiler flags specific to this package and any
136 required libraries that don't support <tt>pkg-config</tt>. If the required
137 libraries support <tt>pkg-config</tt>, they should be added to
138 <tt>Requires</tt> or <tt>Requires.private</tt>.</li>
140 <li><b>Libs</b>: The link flags specific to this package and any required
141 libraries that don't support <tt>pkg-config</tt>. The same rule as
142 <tt>Cflags</tt> applies here.</li>
144 <li><b>Libs.private</b>: The link flags for private libraries required by
145 this package but not exposed to applications. The same rule as
146 <tt>Cflags</tt> applies here.</li>
149 <h2><a name="writing">Writing pkg-config files</a></h2>
151 <p>When creating <tt>pkg-config</tt> files for a package, it is first
152 necessary to decide how they will be distributed. Each file is best used to
153 describe a single library, so each package should have at least as many
154 <tt>pkg-config</tt> files as they do installed libraries.</p>
156 <p>The package name is determined through the filename of the
157 <tt>pkg-config</tt> metadata file. This is the portion of the filename prior
158 to the <tt>.pc</tt> suffix. A common choice is to match the library name to
159 the <tt>.pc</tt> name. For instance, a package installing <tt>libfoo.so</tt>
160 would have a corresponding <tt>libfoo.pc</tt> file containing the
161 <tt>pkg-config</tt> metadata. This choice is not necessary; the <tt>.pc</tt>
162 file should simply be a unique identifier for your library. Following the
163 above example, <tt>foo.pc</tt> or <tt>foolib.pc</tt> would probably work
166 <p>The <tt>Name</tt>, <tt>Description</tt> and <tt>URL</tt> fields are
167 purely informational and should be easy to fill in. The <tt>Version</tt>
168 field is a bit trickier to ensure that it is usable by consumers of the
169 data. <tt>pkg-config</tt> uses the algorithm from
170 <a href="http://rpm.org/">RPM</a> for version comparisons. This works best
171 with a dotted decimal number such as <tt>1.2.3</tt> since letters can cause
172 unexpected results. The number should be monotonically increasing and be
173 as specific as possible in describing the library. Usually it's sufficient
174 to use the package's version number here since it's easy for consumers to
177 <p>Before describing the more useful fields, it will be helpful to
178 demonstrate variable definitions. The most common usage is to define the
179 installation paths so that they don't clutter the metadata fields. Since
180 the variables are expanded recursively, this is very helpful when used in
181 conjunction with autoconf derived paths.</p>
183 <pre>prefix=/usr/local
184 includedir=${prefix}/include
186 Cflags: -I${includedir}/foo</pre>
188 <p>The most important <tt>pkg-config</tt> metadata fields are
189 <tt>Requires</tt>, <tt>Requires.private</tt>, <tt>Cflags</tt>, <tt>Libs</tt>
190 and <tt>Libs.private</tt>. They will define the metadata used by external
191 projects to compile and link with the library.</p>
193 <p><tt>Requires</tt> and <tt>Requires.private</tt> define other modules
194 needed by the library. It is usually preferred to use the private variant of
195 <tt>Requires</tt> to avoid exposing unnecessary libraries to the program
196 that is linking with your library. If the program will not be using the
197 symbols of the required library, it should not be linking directly to that
198 library. See the discussion of
199 <a href="http://wiki.mandriva.com/en/Overlinking">overlinking</a> for a more
200 thorough explanation.</p>
202 <p>Since <tt>pkg-config</tt> always exposes the link flags of the
203 <tt>Requires</tt> libraries, these modules will become direct dependencies
204 of the program. On the other hand, libraries from <tt>Requires.private</tt>
205 will only be included when static linking. For this reason, it is usually
206 only appropriate to add modules from the same package in <tt>Requires</tt>.
209 <p>The <tt>Libs</tt> field contains the link flags necessary to use that
210 library. In addition, <tt>Libs</tt> and <tt>Libs.private</tt> contain link
211 flags for other libraries not supported by <tt>pkg-config</tt>. Similar to
212 the <tt>Requires</tt> field, it is preferred to add link flags for external
213 libraries to the <tt>Libs.private</tt> field so programs do not acquire an
214 additional direct dependency.</p>
216 <p>Finally, the <tt>Cflags</tt> contains the compiler flags for using the
217 library. Unlike the <tt>Libs</tt> field, there is not a private variant of
218 <tt>Cflags</tt>. This is because the data types and macro definitions are
219 needed regardless of the linking scenario.</p>
221 <h2><a name="using">Using pkg-config files</a></h2>
223 <p>Assuming that there are <tt>.pc</tt> files installed on the system, the
224 <tt>pkg-config</tt> tool is used to extract the metadata for usage. A short
225 description of the options can be seen by executing
226 <tt>pkg-config --help</tt>. A more in depth discussion can be found in the
227 <tt>pkg-config(1)</tt> manual page. This section will provide a brief
228 explanation of common usages.</tt>
230 <p>Consider a system with two modules, <tt>foo</tt> and <tt>bar</tt>.
231 Their <tt>.pc</tt> files might look like this:</p>
235 exec_prefix=${prefix}
236 includedir=${prefix}/include
237 libdir=${exec_prefix}/lib
240 Description: The foo library
242 Cflags: -I${includedir}/foo
243 Libs: -L${libdir} -lfoo
247 exec_prefix=${prefix}
248 includedir=${prefix}/include
249 libdir=${exec_prefix}/lib
252 Description: The bar library
254 Requires.private: foo >= 0.7
255 Cflags: -I${includedir}
256 Libs: -L${libdir} -lbar</pre>
258 <p>The version of the modules can be obtained with the <tt>--modversion</tt>
261 <pre>$ pkg-config --modversion foo
263 $ pkg-config --modversion bar
266 <p>To print the link flags needed for each module, use the <tt>--libs</tt>
269 <pre>$ pkg-config --libs foo
271 $ pkg-config --libs bar
274 <p>Notice that <tt>pkg-config</tt> has suppressed part of the <tt>Libs</tt>
275 field for both modules. This is because it treats the <tt>-L</tt> flag
276 specially and knows that the <tt>${libdir}</tt> directory <tt>/usr/lib</tt>
277 is part of the system linker search path. This keeps <tt>pkg-config</tt>
278 from interfering with the linker operation.</p>
280 <p>Also, although <tt>foo</tt> is required by <tt>bar</tt>, the link flags
281 for <tt>foo</tt> are not output. This is because <tt>foo</tt> is not
282 directly needed by an application that only wants to use the <tt>bar</tt>
283 library. For statically linking a <tt>bar</tt> application, we need both
284 sets of linker flags:</p>
286 <pre>$ pkg-config --libs --static bar
289 <p><tt>pkg-config</tt> needs to output both sets of link flags in this case
290 to ensure that the statically linked application will find all the necessary
291 symbols. On the other hand, it will always output all the <tt>Cflags</tt>.
294 <pre>$ pkg-config --cflags bar
296 $ pkg-config --cflags --static bar
297 -I/usr/include/foo</pre>
299 <p>Another useful option, <tt>--exists</tt>, can be used to test for a
300 module's availability.</p>
302 <pre>$ pkg-config --exists foo
306 <p>One of the nicest features of <tt>pkg-config</tt> is providing version
307 checking. It can be used to determine if a sufficient version is available.
310 <pre>$ pkg-config --libs "bar >= 2.7"
311 Requested 'bar >= 2.7' but version of bar is 2.1.2</pre>
313 <p>Some commands will provide more verbose output when combined with the
314 <tt>--print-errors</tt> option.</p>
316 <pre>$ pkg-config --exists --print-errors xoxo
317 Package xoxo was not found in the pkg-config search path.
318 Perhaps you should add the directory containing `xoxo.pc'
319 to the PKG_CONFIG_PATH environment variable
320 No package 'xoxo' found</pre>
322 <p>The message above references the <tt>PKG_CONFIG_PATH</tt> environment
323 variable. This variable is used to augment <tt>pkg-config</tt>'s search
324 path. On a typical Unix system, it will search in the directories
325 <tt>/usr/lib/pkgconfig</tt> and <tt>/usr/share/pkgconfig</tt>. This will
326 usually cover system installed modules. However, some local modules may be
327 installed in a different prefix such as <tt>/usr/local</tt>. In that case,
328 it's necessary to prepend the search path so that <tt>pkg-config</tt> can
329 locate the <tt>.pc</tt> files.</p>
331 <pre>$ pkg-config --modversion hello
332 Package hello was not found in the pkg-config search path.
333 Perhaps you should add the directory containing `hello.pc'
334 to the PKG_CONFIG_PATH environment variable
335 No package 'hello' found
336 $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
337 $ pkg-config --modversion hello
340 <p>A few <a href="http://www.gnu.org/software/autoconf/">autoconf</a> macros
341 are also provided to ease integration of <tt>pkg-config</tt> modules into
345 <li><b>PKG_PROG_PKG_CONFIG([MIN-VERSION])</b>: Locates the
346 <tt>pkg-config</tt> tool on the system and checks the version for
349 <li><b>PKG_CHECK_EXISTS(MODULES, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])</b>:
350 Checks to see whether a particular set of modules exists.</li>
352 <li><b>PKG_CHECK_MODULES(VARIABLE-PREFIX, MODULES, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])</b>:
353 Checks to see whether a particular set of modules exists. If so, it sets
354 <tt><VARIABLE-PREFIX>_CFLAGS</tt> and
355 <tt><VARIABLE-PREFIX>_LIBS</tt> according to the output from
356 <tt>pkg-config --cflags</tt> and <tt>pkg-config --libs</tt>.</li>
359 <!--<h2><a name="examples">Examples</a></h2>-->
360 <h2><a name="faq">Frequently asked questions</a></h2>
363 <li>My program uses library <tt>x</tt>. What do I do?</li>
365 <p>The <tt>pkg-config</tt> output can easily be used on the compiler
366 command line. Assuming the <tt>x</tt> library has a <tt>x.pc</tt>
367 <tt>pkg-config</tt> file:</p>
369 <pre>cc `pkg-config --cflags --libs x` -o myapp myapp.c</pre>
371 <p>The integration can be more robust when used with
372 <a href="http://www.gnu.org/software/autoconf/">autoconf</a> and
373 <a href="http://www.gnu.org/software/automake/">automake</a>. By using the
374 supplied <tt>PKG_CHECK_MODULES</tt> macro, the metadata is easily accessed
375 in the build process.</p>
378 PKG_CHECK_MODULES([X], [x])
381 myapp_CFLAGS = $(X_CFLAGS)
382 myapp_LDADD = $(X_LIBS)</pre>
384 <p>If the <tt>x</tt> module is found, the macro will fill and substitute
385 the <tt>X_CFLAGS</tt> and <tt>X_LIBS</tt> variables. If the module is not
386 found, an error will be produced. Optional 3rd and 4th arguments can be
387 supplied to <tt>PKG_CHECK_MODULES</tt> to control actions when the module
390 <li>My library <tt>z</tt> installs header files which include <tt>libx</tt>
391 headers. What do I put in my <tt>z.pc</tt> file?</li>
393 <p>If the <tt>x</tt> library has <tt>pkg-config</tt> support, add it to
394 the <tt>Requires.private</tt> field. If it does not, augment the
395 <tt>Cflags</tt> field with the necessary compiler flags for using the
396 <tt>libx</tt> headers. In either case, <tt>pkg-config</tt> will output
397 the compiler flags when <tt>--static</tt> is used or not.</p>
399 <li>My library <tt>z</tt> uses <tt>libx</tt> internally, but does not
400 expose <tt>libx</tt> data types in its public API. What do I put in my
401 <tt>z.pc</tt> file?</li>
403 <p>Again, add the module to <tt>Requires.private</tt> if it supports
404 <tt>pkg-config</tt>. In this case, the compiler flags will be emitted
405 unnecessarily, but it ensures that the linker flags will be present when
406 linking statically. If <tt>libx</tt> does not support <tt>pkg-config</tt>,
407 add the necessary linker flags to <tt>Libs.private</tt>.</p>
412 <address>Dan Nicholson <dbn.lists (at) gmail (dot) com></address>
414 <p>Copyright (C) 2010 Dan Nicholson.<br/>
415 This document is licensed under the
416 <a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt">GNU General Public License, Version 2</a>
417 or any later version.</p>