pkg-config-guide.html

   1 <!--
   2 Copyright (C) 2010  Dan Nicholson.
   3
   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.
   8
   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.
  13
  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.
  17 -->
  18
  19 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  20     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  21
  22 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
  23 <head>
  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; }
  27   </style>
  28
  29   <title>Guide to pkg-config</title>
  30 </head>
  31
  32 <body>
  33   <h1><a name="top">Guide to pkg-config</a></h1>
  34
  35   <h3>Dan Nicholson</h3>
  36
  37   <ul>
  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>
  45   </ul>
  46
  47   <h2><a name="overview">Overview</a></h2>
  48
  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>
  54
  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>
  58
  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
  61   other platforms.</p>
  62
  63   <h2><a name="why">Why?</a></h2>
  64
  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.
  69   </p>
  70
  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>
  75
  76   <h2><a name="concepts">Concepts</a></h2>
  77
  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>
  83
  84   <p>The file format contains predefined metadata keywords and freeform
  85   variables. An example may be illustrative:<p>
  86
  87 <pre>prefix=/usr/local
  88 exec_prefix=${prefix}
  89 includedir=${prefix}/include
  90 libdir=${exec_prefix}/lib
  91
  92 Name: foo
  93 Description: The foo library
  94 Version: 1.0.0
  95 Cflags: -I${includedir}/foo
  96 Libs: -L${libdir} -lfoo</pre>
  97
  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>
 104
 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>
 108
 109   <ul>
 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>
 113
 114     <li><b>Description</b>: A brief description of the package.</li>
 115
 116     <li><b>URL</b>: An URL where people can get more information about and
 117     download the package.</li>
 118
 119     <li><b>Version</b>: A string specifically defining the version of the
 120     package.</li>
 121
 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     =, &lt;, &gt;, &lt;= or &gt;=.</li>
 125
 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>
 129
 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>
 134
 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>
 139
 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>
 143
 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>
 147   </ul>
 148
 149   <h2><a name="writing">Writing pkg-config files</a></h2>
 150
 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>
 155
 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
 164   just as well.</p>
 165
 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
 175   track.</p>
 176
 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>
 182
 183 <pre>prefix=/usr/local
 184 includedir=${prefix}/include
 185
 186 Cflags: -I${includedir}/foo</pre>
 187
 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>
 192
 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>
 201
 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>.
 207   </p>
 208
 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>
 215
 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>
 220
 221   <h2><a name="using">Using pkg-config files</a></h2>
 222
 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>
 229
 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>
 232
 233 <pre>foo.pc:
 234 prefix=/usr
 235 exec_prefix=${prefix}
 236 includedir=${prefix}/include
 237 libdir=${exec_prefix}/lib
 238
 239 Name: foo
 240 Description: The foo library
 241 Version: 1.0.0
 242 Cflags: -I${includedir}/foo
 243 Libs: -L${libdir} -lfoo
 244
 245 bar.pc:
 246 prefix=/usr
 247 exec_prefix=${prefix}
 248 includedir=${prefix}/include
 249 libdir=${exec_prefix}/lib
 250
 251 Name: bar
 252 Description: The bar library
 253 Version: 2.1.2
 254 Requires.private: foo >= 0.7
 255 Cflags: -I${includedir}
 256 Libs: -L${libdir} -lbar</pre>
 257
 258   <p>The version of the modules can be obtained with the <tt>--modversion</tt>
 259   option.</p>
 260
 261 <pre>$ pkg-config --modversion foo
 262 1.0.0
 263 $ pkg-config --modversion bar
 264 2.1.2</pre>
 265
 266   <p>To print the link flags needed for each module, use the <tt>--libs</tt>
 267   option.</p>
 268
 269 <pre>$ pkg-config --libs foo
 270 -lfoo
 271 $ pkg-config --libs bar
 272 -lbar</pre>
 273
 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>
 279
 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>
 285
 286 <pre>$ pkg-config --libs --static bar
 287 -lbar -lfoo</pre>
 288
 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>.
 292   </p>
 293
 294 <pre>$ pkg-config --cflags bar
 295 -I/usr/include/foo
 296 $ pkg-config --cflags --static bar
 297 -I/usr/include/foo</pre>
 298
 299   <p>Another useful option, <tt>--exists</tt>, can be used to test for a
 300   module's availability.</p>
 301
 302 <pre>$ pkg-config --exists foo
 303 $ echo $?
 304 0</pre>
 305
 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.
 308   </p>
 309
 310 <pre>$ pkg-config --libs "bar >= 2.7"
 311 Requested 'bar >= 2.7' but version of bar is 2.1.2</pre>
 312
 313   <p>Some commands will provide more verbose output when combined with the
 314   <tt>--print-errors</tt> option.</p>
 315
 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>
 321
 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>
 330
 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
 338 1.0.0</pre>
 339
 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
 342   projects.</p>
 343
 344   <ul>
 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
 347     compatibility.</li>
 348
 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>
 351
 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>&lt;VARIABLE-PREFIX&gt;_CFLAGS</tt> and
 355     <tt>&lt;VARIABLE-PREFIX&gt;_LIBS</tt> according to the output from
 356     <tt>pkg-config --cflags</tt> and <tt>pkg-config --libs</tt>.</li>
 357   </ul>
 358
 359   <!--<h2><a name="examples">Examples</a></h2>-->
 360   <h2><a name="faq">Frequently asked questions</a></h2>
 361
 362   <ol>
 363     <li>My program uses library <tt>x</tt>. What do I do?</li>
 364
 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>
 368
 369 <pre>cc `pkg-config --cflags --libs x` -o myapp myapp.c</pre>
 370
 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>
 376
 377 <pre>configure.ac:
 378 PKG_CHECK_MODULES([X], [x])
 379
 380 Makefile.am:
 381 myapp_CFLAGS = $(X_CFLAGS)
 382 myapp_LDADD = $(X_LIBS)</pre>
 383
 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
 388     is found or not.</p>
 389
 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>
 392
 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>
 398
 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>
 402
 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>
 408   </ol>
 409
 410   <hr/>
 411
 412   <address>Dan Nicholson &lt;dbn.lists (at) gmail (dot) com&gt;</address>
 413
 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>
 418
 419 </body>
 420 </html>