pkg-config.1

   1 .\"
   2 .\" pkg-config manual page.
   3 .\" (C) Red Hat, Inc. based on gnome-config man page (C) Miguel de Icaza (miguel@gnu.org)
   4 .\"
   5 .
   6 .TH pkg-config 1
   7 .SH NAME
   8 pkg-config \- Return metainformation about installed libraries
   9 .SH SYNOPSIS
  10 .PP
  11 .B pkg-config
  12 [\-\-modversion] [\-\-version] [\-\-help] [\-\-print-errors]
  13 [\-\-silence-errors] [\-\-errors-to-stdout] [\-\-debug]
  14 [\-\-cflags] [\-\-libs] [\-\-libs-only-L]
  15 [\-\-libs-only-l] [\-\-cflags-only-I]
  16 [\-\-variable=VARIABLENAME]
  17 [\-\-define-variable=VARIABLENAME=VARIABLEVALUE]
  18 [\-\-print-variables]
  19 [\-\-uninstalled]
  20 [\-\-exists] [\-\-atleast-version=VERSION] [\-\-exact-version=VERSION]
  21 [\-\-max-version=VERSION] [\-\-list\-all] [LIBRARIES...]
  22 [\-\-print-provides] [\-\-print-requires] [\-\-print-requires-private] [LIBRARIES...]
  23 .SH DESCRIPTION
  24
  25 The \fIpkg-config\fP program is used to retrieve information about
  26 installed libraries in the system.  It is typically used to compile
  27 and link against one or more libraries.  Here is a typical usage
  28 scenario in a Makefile:
  29 .PP
  30 .nf
  31 program: program.c
  32         cc program.c $(pkg-config --cflags --libs gnomeui)
  33 .fi
  34 .PP
  35 .I pkg-config
  36 retrieves information about packages from special metadata
  37 files. These files are named after the package, and has a
  38 .I .pc
  39 extension.  On most systems, \fIpkg-config\fP looks in
  40 .I /usr/lib/pkgconfig, /usr/share/pkgconfig, /usr/local/lib/pkgconfig
  41 and
  42 .I /usr/local/share/pkgconfig
  43 for these files.  It will additionally look in the colon-separated
  44 (on Windows, semicolon-separated) list of directories specified by the
  45 PKG_CONFIG_PATH environment variable.
  46 .PP
  47 The package name specified on the \fIpkg-config\fP command line is
  48 defined to be the name of the metadata file, minus the \fI.pc\fP
  49 extension. If a library can install multiple versions simultaneously,
  50 it must give each version its own name (for example, GTK 1.2 might
  51 have the package name "gtk+" while GTK 2.0 has "gtk+-2.0").
  52 .PP
  53 In addition to specifying a package name on the command line, the full
  54 path to a given \fI.pc\fP file may be given instead. This allows a
  55 user to directly query a particular \fI.pc\fP file.
  56 .\"
  57 .SH OPTIONS
  58 The following options are supported:
  59 .TP
  60 .I "--modversion"
  61 Requests that the version information of the libraries specified on
  62 the command line be displayed.  If \fIpkg-config\fP can find all the
  63 libraries on the command line, each library's version string is
  64 printed to stdout, one version per line. In this case \fIpkg-config\fP
  65 exits successfully. If one or more libraries is unknown,
  66 .I pkg-config
  67 exits with a nonzero code, and the contents of stdout are undefined.
  68 .TP
  69 .I "--version"
  70 Displays the version of
  71 .I pkg-config
  72 and terminates.
  73 .TP
  74 .I "--help"
  75 Displays a help message and terminates.
  76 .TP
  77 .I "--print-errors"
  78 If one or more of the modules on the command line, or their
  79 dependencies, are not found, or if an error occurs in parsing
  80 a \fI.pc\fP file, then this option will cause errors explaining the
  81 problem to be printed. With "predicate" options such as "--exists"
  82 .I "pkg-config"
  83 runs silently by default, because it's usually used
  84 in scripts that want to control what's output. This option can be used
  85 alone (to just print errors encountered locating modules on the
  86 command line) or with other options. The PKG_CONFIG_DEBUG_SPEW
  87 environment variable overrides this option.
  88 .TP
  89 .I "--silence-errors"
  90 If one or more of the modules on the command line, or their
  91 dependencies, are not found, or if an error occurs in parsing a
  92 a \fI.pc\fP file, then this option will keep errors explaining the
  93 problem from being printed. With "predicate" options such as
  94 "--exists" \fIpkg-config\fP runs silently by default, because it's
  95 usually used in scripts that want to control what's output. So this
  96 option is only useful with options such as "--cflags" or
  97 "--modversion" that print errors by default. The PKG_CONFIG_DEBUG_SPEW
  98 environment variable overrides this option.
  99 .TP
 100 .I "--errors-to-stdout"
 101 If printing errors, print them to stdout rather than the default stderr
 102 .TP
 103 .I "--debug"
 104 Print debugging information. This is slightly different than the
 105 PKG_CONFIG_DEBUG_SPEW environment variable, which also enable
 106 "--print-errors".
 107
 108 .PP
 109 The following options are used to compile and link programs:
 110 .TP
 111 .I "--cflags"
 112 This prints pre-processor and compile flags required to compile the
 113 packages on the command line, including flags for all their
 114 dependencies. Flags are "compressed" so that each identical flag
 115 appears only once. \fIpkg-config\fP exits with a nonzero code if it
 116 can't find metadata for one or more of the packages on the command
 117 line.
 118 .TP
 119 .I "--cflags-only-I"
 120 This prints the -I part of "--cflags". That is, it defines the header
 121 search path but doesn't specify anything else.
 122 .TP
 123 .I "--libs"
 124 This option is identical to "--cflags", only it prints the link
 125 flags. As with "--cflags", duplicate flags are merged (maintaining
 126 proper ordering), and flags for dependencies are included in the
 127 output.
 128 .TP
 129 .I "--libs-only-L"
 130 This prints the -L/-R part of "--libs". That is, it defines the
 131 library search path but doesn't specify which libraries to link with.
 132 .TP
 133 .I "--libs-only-l"
 134 This prints the -l part of "--libs" for the libraries specified on
 135 the command line. Note that the union of "--libs-only-l" and
 136 "--libs-only-L" may be smaller than "--libs", due to flags such as
 137 -rdynamic.
 138 .TP
 139 .I "--variable=VARIABLENAME"
 140 This returns the value of a variable defined in a package's \fI.pc\fP
 141 file. Most packages define the variable "prefix", for example, so you
 142 can say:
 143 .nf
 144   $ pkg-config --variable=prefix glib-2.0
 145   /usr/
 146 .fi
 147 .TP
 148 .I "--define-variable=VARIABLENAME=VARIABLEVALUE"
 149 This sets a global value for a variable, overriding the value in any
 150 .I .pc
 151 files. Most packages define the variable "prefix", for example, so you
 152 can say:
 153 .nf
 154   $ pkg-config --print-errors --define-variable=prefix=/foo \e
 155                --variable=prefix glib-2.0
 156   /foo
 157 .fi
 158 .TP
 159 .I "--print-variables"
 160 Returns a list of all variables defined in the package.
 161
 162 .TP
 163 .I "--uninstalled"
 164 Normally if you request the package "foo" and the package
 165 "foo-uninstalled" exists, \fIpkg-config\fP will prefer the
 166 "-uninstalled" variant. This allows compilation/linking against
 167 uninstalled packages. If you specify the "--uninstalled" option,
 168 .I pkg-config
 169 will return successfully if any "-uninstalled" packages are being
 170 used, and return failure (false) otherwise.  (The
 171 PKG_CONFIG_DISABLE_UNINSTALLED environment variable keeps
 172 .I pkg-config
 173 from implicitly choosing "-uninstalled" packages, so if that variable
 174 is set, they will only have been used if you pass a name like
 175 "foo-uninstalled" on the command line explicitly.)
 176 .TP
 177 .I "--exists"
 178 .TP
 179 .I "--atleast-version=VERSION"
 180 .TP
 181 .I "--exact-version=VERSION"
 182 .TP
 183 .I "--max-version=VERSION"
 184 These options test whether the package or list of packages on the
 185 command line are known to \fIpkg-config\fP, and optionally whether the
 186 version number of a package meets certain constraints.  If all packages
 187 exist and meet the specified version constraints,
 188 .I pkg-config
 189 exits successfully. Otherwise it exits unsuccessfully. Only the first
 190 VERSION comparing option will be honored. Subsequent options of this
 191 type will be ignored.
 192
 193 Rather than using the version-test options, you can simply give a version
 194 constraint after each package name, for example:
 195 .nf
 196   $ pkg-config --exists 'glib-2.0 >= 1.3.4 libxml = 1.8.3'
 197 .fi
 198 Remember to use \-\-print-errors if you want error messages. When no
 199 output options are supplied to \fIpkg-config\fP, \-\-exists is implied.
 200 .TP
 201 .I "--msvc-syntax"
 202 This option is available only on Windows. It causes \fIpkg-config\fP
 203 to output -l and -L flags in the form recognized by the Microsoft
 204 Visual C++ command-line compiler, \fIcl\fP. Specifically, instead of
 205 .I -Lx:/some/path
 206 it prints \fI/libpath:x/some/path\fP, and instead of \fI-lfoo\fP it
 207 prints \fIfoo.lib\fP. Note that the --libs output consists of flags
 208 for the linker, and should be placed on the cl command line after a
 209 /link switch.
 210 .TP
 211 .I "--dont-define-prefix"
 212 This option is available only on Windows. It prevents \fIpkg-config\fP
 213 from automatically trying to override the value of the variable
 214 "prefix" in each .pc file.
 215 .TP
 216 .I "--prefix-variable=PREFIX"
 217 Also this option is available only on Windows. It sets the name of the
 218 variable that \fIpkg-config\fP automatically sets as described above.
 219 .TP
 220 .I "--static"
 221 Output libraries suitable for static linking.  That means including
 222 any private libraries in the output.  This relies on proper tagging in
 223 the .pc files, else a too large number of libraries will ordinarily be
 224 output.
 225 .TP
 226 .I "--list-all"
 227 List all modules found in the \fIpkg-config\fP path.
 228 .TP
 229 .I "--print-provides"
 230 List all modules the given packages provides.
 231 .TP
 232 .I "--print-requires"
 233 List all modules the given packages requires.
 234 .TP
 235 .I "--print-requires-private"
 236 List all modules the given packages requires for static linking (see --static).
 237 .\"
 238 .SH ENVIRONMENT VARIABLES
 239 .TP
 240 .I "PKG_CONFIG_PATH"
 241 A colon-separated (on Windows, semicolon-separated) list of
 242 directories to search for .pc files.  The default directory will
 243 always be searched after searching the path; the default is
 244 .I \%libdir/\fPpkgconfig:\fIdatadir\fP/pkgconfig where \fIlibdir\fP is
 245 the libdir for \fIpkg-config\fP and \fIdatadir\fP is the datadir
 246 for \fIpkg-config\fP when it was installed.
 247 .TP
 248 .I "PKG_CONFIG_DEBUG_SPEW"
 249 If set, causes \fIpkg-config\fP to print all kinds of
 250 debugging information and report all errors.
 251 .TP
 252 .I "PKG_CONFIG_TOP_BUILD_DIR"
 253 A value to set for the magic variable \fIpc_top_builddir\fP
 254 which may appear in \fI.pc\fP files. If the environment variable is
 255 not set, the default value '$(top_builddir)' will be used. This
 256 variable should refer to the top builddir of the Makefile where the
 257 compile/link flags reported by \fIpkg-config\fP will be used.
 258 This only matters when compiling/linking against a package that hasn't
 259 yet been installed.
 260 .TP
 261 .I "PKG_CONFIG_DISABLE_UNINSTALLED"
 262 Normally if you request the package "foo" and the package
 263 "foo-uninstalled" exists, \fIpkg-config\fP will prefer the
 264 "-uninstalled" variant. This allows compilation/linking against
 265 uninstalled packages.  If this environment variable is set, it
 266 disables said behavior.
 267 .TP
 268 .I "PKG_CONFIG_ALLOW_SYSTEM_CFLAGS"
 269 Don't strip -I/usr/include out of cflags.
 270 .TP
 271 .I "PKG_CONFIG_ALLOW_SYSTEM_LIBS"
 272 Don't strip -L/usr/lib or -L/lib out of libs.
 273 .TP
 274 .I "PKG_CONFIG_SYSROOT_DIR"
 275 Modify -I and -L to use the directories located in target sysroot.
 276 this option is useful when cross-compiling packages that use pkg-config
 277 to determine CFLAGS and LDFLAGS. -I and -L are modified to point to
 278 the new system root. this means that a -I/usr/include/libfoo will
 279 become -I/var/target/usr/include/libfoo with a PKG_CONFIG_SYSROOT_DIR
 280 equal to /var/target (same rule apply to -L)
 281 .TP
 282 .I "PKG_CONFIG_LIBDIR"
 283 Replaces the default \fIpkg-config\fP search directory, usually \fI/usr/lib/pkgconfig\fP
 284 .\"
 285 .SH QUERYING PKG-CONFIG'S DEFAULTS
 286 .I pkg-config
 287 can be used to query itself for the default search path, version number
 288 and other information, for instance using:
 289 .nf
 290   $ pkg-config --variable pc_path pkg-config
 291 .fi
 292 or
 293 .nf
 294   $ pkg-config --modversion pkg-config
 295 .fi
 296 .SH WINDOWS SPECIALITIES
 297 If a .pc file is found in a directory that matches the usual
 298 conventions (i.e., ends with \\lib\\pkgconfig or \\share\\pkgconfig),
 299 the prefix for that package is assumed to be the grandparent of the
 300 directory where the file was found, and the \fIprefix\fP variable is
 301 overridden for that file accordingly.
 302
 303 If the value of a variable in a .pc file begins with the original,
 304 non-overridden, value of the \fIprefix\fP variable, then the overridden
 305 value of \fIprefix\fP is used instead.
 306 .\"
 307 .SH AUTOCONF MACROS
 308 .TP
 309 .I "PKG_CHECK_MODULES(VARIABLE-PREFIX, MODULES [,ACTION-IF-FOUND [,ACTION-IF-NOT-FOUND]])"
 310
 311 The macro PKG_CHECK_MODULES can be used in \fIconfigure.ac\fP to
 312 check whether modules exist. A typical usage would be:
 313 .nf
 314  PKG_CHECK_MODULES([MYSTUFF], [gtk+-2.0 >= 1.3.5 libxml = 1.8.4])
 315 .fi
 316
 317 This would result in MYSTUFF_LIBS and MYSTUFF_CFLAGS substitution
 318 variables, set to the libs and cflags for the given module list.
 319 If a module is missing or has the wrong version, by default configure
 320 will abort with a message. To replace the default action,
 321 specify an \%ACTION-IF-NOT-FOUND. \%PKG_CHECK_MODULES will not print any
 322 error messages if you specify your own ACTION-IF-NOT-FOUND.
 323 However, it will set the variable MYSTUFF_PKG_ERRORS, which you can
 324 use to display what went wrong.
 325
 326 Note that if there is a possibility the first call to
 327 PKG_CHECK_MODULES might not happen, you should be sure to include an
 328 explicit call to PKG_PROG_PKG_CONFIG in your configure.ac.
 329
 330 Also note that repeated usage of VARIABLE-PREFIX is not recommended.
 331 After the first successful usage, subsequent calls with the same
 332 VARIABLE-PREFIX will simply use the _LIBS and _CFLAGS variables set from
 333 the previous usage without calling \fIpkg-config\fP again.
 334 .\"
 335 .TP
 336 .I "PKG_PROG_PKG_CONFIG([MIN-VERSION])"
 337
 338 Defines the PKG_CONFIG variable to the best pkg-config available,
 339 useful if you need pkg-config but don't want to use PKG_CHECK_MODULES.
 340 .\"
 341 .TP
 342 .I "PKG_CHECK_EXISTS(MODULES, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])"
 343
 344 Check to see whether a particular set of modules exists.  Similar
 345 to PKG_CHECK_MODULES(), but does not set variables or print errors.
 346
 347 Similar to PKG_CHECK_MODULES, make sure that the first instance of
 348 this or PKG_CHECK_MODULES is called, or make sure to call
 349 PKG_CHECK_EXISTS manually.
 350 .TP
 351 .I "PKG_INSTALLDIR(DIRECTORY)"
 352
 353 Substitutes the variable pkgconfigdir as the location where a module
 354 should install pkg-config .pc files. By default the directory is
 355 $libdir/pkgconfig, but the default can be changed by passing DIRECTORY.
 356 The user can override through the --with-pkgconfigdir parameter.
 357 .TP
 358 .I "PKG_NOARCH_INSTALLDIR(DIRECTORY)"
 359
 360 Substitutes the variable noarch_pkgconfigdir as the location where a
 361 module should install arch-independent pkg-config .pc files. By default
 362 the directory is $datadir/pkgconfig, but the default can be changed by
 363 passing DIRECTORY. The user can override through the
 364 --with-noarch-pkgconfigdir parameter.
 365 .TP
 366 .I "PKG_CHECK_VAR(VARIABLE, MODULE, CONFIG-VARIABLE, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])"
 367
 368 Retrieves the value of the pkg-config variable CONFIG-VARIABLE from
 369 MODULE and stores it in VARIABLE. Note that repeated usage of VARIABLE
 370 is not recommended as the check will be skipped if the variable is
 371 already set.
 372
 373 .SH METADATA FILE SYNTAX
 374 To add a library to the set of packages \fIpkg-config\fP knows about,
 375 simply install a \fI.pc\fP file. You should install this file to
 376 .I libdir\fP/pkgconfig.
 377 .PP
 378 Here is an example file:
 379 .nf
 380 # This is a comment
 381 prefix=/home/hp/unst   # this defines a variable
 382 exec_prefix=${prefix}  # defining another variable in terms of the first
 383 libdir=${exec_prefix}/lib
 384 includedir=${prefix}/include
 385
 386 Name: GObject                            # human-readable name
 387 Description: Object/type system for GLib # human-readable description
 388 Version: 1.3.1
 389 URL: http://www.gtk.org
 390 Requires: glib-2.0 = 1.3.1
 391 Conflicts: foobar <= 4.5
 392 Libs: -L${libdir} -lgobject-1.3
 393 Libs.private: -lm
 394 Cflags: -I${includedir}/glib-2.0 -I${libdir}/glib/include
 395 .fi
 396 .PP
 397 You would normally generate the file using configure, so that the
 398 prefix, etc. are set to the proper values.  The GNU Autoconf manual
 399 recommends generating files like .pc files at build time rather than
 400 configure time, so when you build the .pc file is a matter of taste
 401 and preference.
 402 .PP
 403 Files have two kinds of line: keyword lines start with a keyword plus
 404 a colon, and variable definitions start with an alphanumeric string
 405 plus an equals sign. Keywords are defined in advance and have special
 406 meaning to \fIpkg-config\fP; variables do not, you can have any
 407 variables that you wish (however, users may expect to retrieve the
 408 usual directory name variables).
 409 .PP
 410 Note that variable references are written "${foo}"; you can escape
 411 literal "${" as "$${".
 412 .TP
 413 .I "Name:"
 414 This field should be a human-readable name for the package. Note that
 415 it is not the name passed as an argument to \fIpkg-config\fP.
 416 .TP
 417 .I "Description:"
 418 This should be a brief description of the package
 419 .TP
 420 .I "URL:"
 421 An URL where people can get more information about and download the package
 422 .TP
 423 .I "Version:"
 424 This should be the most-specific-possible package version string.
 425 .TP
 426 .I "Requires:"
 427 This is a comma-separated list of packages that are required by your
 428 package. Flags from dependent packages will be merged in to the flags
 429 reported for your package. Optionally, you can specify the version
 430 of the required package (using the operators =, <, >, >=, <=);
 431 specifying a version allows \fIpkg-config\fP to perform extra sanity
 432 checks. You may only mention the same package one time on the
 433 .I "Requires:"
 434 line. If the version of a package is unspecified, any version will
 435 be used with no checking.
 436 .TP
 437 .I Requires.private:
 438 A list of packages required by this package. The difference from
 439 .I Requires
 440 is that the packages listed under
 441 .I Requires.private
 442 are not taken into account when a flag list is computed for
 443 dynamically linked executable (i.e., when \-\-static was not
 444 specified).  In the situation where each .pc file corresponds to a
 445 library,
 446 .I Requires.private
 447 shall be used exclusively to specify the dependencies between the
 448 libraries.
 449 .TP
 450 .I "Conflicts:"
 451 This optional line allows \fIpkg-config\fP to perform additional
 452 sanity checks, primarily to detect broken user installations.  The
 453 syntax is the same as
 454 .I "Requires:"
 455 except that
 456 you can list the same package more than once here, for example
 457 "foobar = 1.2.3, foobar = 1.2.5, foobar >= 1.3", if you have reason to
 458 do so. If a version isn't specified, then your package conflicts with
 459 all versions of the mentioned package.
 460 If a user tries to use your package and a conflicting package at the
 461 same time, then \fIpkg-config\fP will complain.
 462 .TP
 463 .I "Libs:"
 464 This line should give the link flags specific to your package.
 465 Don't add any flags for required packages; \fIpkg-config\fP will
 466 add those automatically.
 467 .TP
 468 .I "Libs.private:"
 469 This line should list any private libraries in use.  Private libraries
 470 are libraries which are not exposed through your library, but are
 471 needed in the case of static linking. This differs from
 472 .I Requires.private
 473 in that it references libraries that do not have package files
 474 installed.
 475 .TP
 476 .I "Cflags:"
 477 This line should list the compile flags specific to your package.
 478 Don't add any flags for required packages; \fIpkg-config\fP will
 479 add those automatically.
 480 .\"
 481 .SH AUTHOR
 482
 483 .I pkg-config
 484 was written by James Henstridge, rewritten by Martijn van Beers, and
 485 rewritten again by Havoc Pennington. Tim Janik, Owen Taylor, and Raja
 486 Harinath submitted suggestions and some code.
 487 .I gnome-config
 488 was written by Miguel de Icaza, Raja Harinath and various hackers in
 489 the GNOME team.  It was inspired by Owen Taylor's \fIgtk-config\fP
 490 program.
 491 .\"
 492 .SH BUGS
 493
 494 \fIpkg-config\fP does not handle mixing of parameters with and without
 495 = well.  Stick with one.
 496
 497 Bugs can be reported at http://bugs.freedesktop.org/ under the
 498 .I pkg-config
 499 component.