1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
|
<!--
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>
|
