github.com/cellofellow/gopkg@v0.0.0-20140722061823-eec0544a62ad/apps/pkg-config/doc/pkg-config-guide.html (about) 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 =, <, >, <= or >=.</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><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> 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 <dbn.lists (at) gmail (dot) com></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>