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.
 190
 191 Rather than using the version-test options, you can simply give a version
 192 constraint after each package name, for example:
 193 .nf
 194   $ pkg-config --exists 'glib-2.0 >= 1.3.4 libxml = 1.8.3'
 195 .fi
 196 Remember to use \-\-print-errors if you want error messages.
 197 .TP
 198 .I "--msvc-syntax"
 199 This option is available only on Windows. It causes \fIpkg-config\fP
 200 to output -l and -L flags in the form recognized by the Microsoft
 201 Visual C++ command-line compiler, \fIcl\fP. Specifically, instead of
 202 .I -Lx:/some/path
 203 it prints \fI/libpath:x/some/path\fP, and instead of \fI-lfoo\fP it
 204 prints \fIfoo.lib\fP. Note that the --libs output consists of flags
 205 for the linker, and should be placed on the cl command line after a
 206 /link switch.
 207 .TP
 208 .I "--dont-define-prefix"
 209 This option is available only on Windows. It prevents \fIpkg-config\fP
 210 from automatically trying to override the value of the variable
 211 "prefix" in each .pc file.
 212 .TP
 213 .I "--prefix-variable=PREFIX"
 214 Also this option is available only on Windows. It sets the name of the
 215 variable that \fIpkg-config\fP automatically sets as described above.
 216 .TP
 217 .I "--static"
 218 Output libraries suitable for static linking.  That means including
 219 any private libraries in the output.  This relies on proper tagging in
 220 the .pc files, else a too large number of libraries will ordinarily be
 221 output.
 222 .TP
 223 .I "--list-all"
 224 List all modules found in the \fIpkg-config\fP path.
 225 .TP
 226 -I "--print-provides"
 227 List all modules the given packages provides.
 228 .TP
 229 .I "--print-requires"
 230 List all modules the given packages requires.
 231 .TP
 232 .I "--print-requires-private"
 233 List all modules the given packages requires for static linking (see --static).
 234 .\"
 235 .SH ENVIRONMENT VARIABLES
 236 .TP
 237 .I "PKG_CONFIG_PATH"
 238 A colon-separated (on Windows, semicolon-separated) list of
 239 directories to search for .pc files.  The default directory will
 240 always be searched after searching the path; the default is
 241 .I \%libdir/\fPpkgconfig:\fIdatadir\fP/pkgconfig where \fIlibdir\fP is
 242 the libdir for \fIpkg-config\fP and \fIdatadir\fP is the datadir
 243 for \fIpkg-config\fP when it was installed.
 244 .TP
 245 .I "PKG_CONFIG_DEBUG_SPEW"
 246 If set, causes \fIpkg-config\fP to print all kinds of
 247 debugging information and report all errors.
 248 .TP
 249 .I "PKG_CONFIG_TOP_BUILD_DIR"
 250 A value to set for the magic variable \fIpc_top_builddir\fP
 251 which may appear in \fI.pc\fP files. If the environment variable is
 252 not set, the default value '$(top_builddir)' will be used. This
 253 variable should refer to the top builddir of the Makefile where the
 254 compile/link flags reported by \fIpkg-config\fP will be used.
 255 This only matters when compiling/linking against a package that hasn't
 256 yet been installed.
 257 .TP
 258 .I "PKG_CONFIG_DISABLE_UNINSTALLED"
 259 Normally if you request the package "foo" and the package
 260 "foo-uninstalled" exists, \fIpkg-config\fP will prefer the
 261 "-uninstalled" variant. This allows compilation/linking against
 262 uninstalled packages.  If this environment variable is set, it
 263 disables said behavior.
 264 .TP
 265 .I "PKG_CONFIG_ALLOW_SYSTEM_CFLAGS"
 266 Don't strip -I/usr/include out of cflags.
 267 .TP
 268 .I "PKG_CONFIG_ALLOW_SYSTEM_LIBS"
 269 Don't strip -L/usr/lib out of libs
 270 .TP
 271 .I "PKG_CONFIG_SYSROOT_DIR"
 272 Modify -I and -L to use the directories located in target sysroot.
 273 this option is useful when cross-compiling packages that use pkg-config
 274 to determine CFLAGS and LDFLAGS. -I and -L are modified to point to
 275 the new system root. this means that a -I/usr/include/libfoo will
 276 become -I/var/target/usr/include/libfoo with a PKG_CONFIG_SYSROOT_DIR
 277 equal to /var/target (same rule apply to -L)
 278 .TP
 279 .I "PKG_CONFIG_LIBDIR"
 280 Replaces the default \fIpkg-config\fP search directory, usually \fI/usr/lib/pkgconfig\fP
 281 .\"
 282 .SH QUERYING PKG-CONFIG'S DEFAULTS
 283 .I pkg-config
 284 can be used to query itself for the default search path, version number
 285 and other information, for instance using:
 286 .nf
 287   $ pkg-config --variable pc_path pkg-config
 288 .fi
 289 or
 290 .nf
 291   $ pkg-config --modversion pkg-config
 292 .fi
 293 .SH WINDOWS SPECIALITIES
 294 If a .pc file is found in a directory that matches the usual
 295 conventions (i.e., ends with \\lib\\pkgconfig or \\share\\pkgconfig),
 296 the prefix for that package is assumed to be the grandparent of the
 297 directory where the file was found, and the \fIprefix\fP variable is
 298 overridden for that file accordingly.
 299
 300 If the value of a variable in a .pc file begins with the original,
 301 non-overridden, value of the \fIprefix\fP variable, then the overridden
 302 value of \fIprefix\fP is used instead.
 303 .\"
 304 .SH AUTOCONF MACROS
 305 .TP
 306 .I "PKG_CHECK_MODULES(VARIABLE-PREFIX, MODULES [,ACTION-IF-FOUND [,ACTION-IF-NOT-FOUND]])"
 307
 308 The macro PKG_CHECK_MODULES can be used in \fIconfigure.ac\fP to
 309 check whether modules exist. A typical usage would be:
 310 .nf
 311  PKG_CHECK_MODULES([MYSTUFF], [gtk+-2.0 >= 1.3.5 libxml = 1.8.4])
 312 .fi
 313
 314 This would result in MYSTUFF_LIBS and MYSTUFF_CFLAGS substitution
 315 variables, set to the libs and cflags for the given module list.
 316 If a module is missing or has the wrong version, by default configure
 317 will abort with a message. To replace the default action,
 318 specify an \%ACTION-IF-NOT-FOUND. \%PKG_CHECK_MODULES will not print any
 319 error messages if you specify your own ACTION-IF-NOT-FOUND.
 320 However, it will set the variable MYSTUFF_PKG_ERRORS, which you can
 321 use to display what went wrong.
 322
 323 Note that if there is a possibility the first call to
 324 PKG_CHECK_MODULES might not happen, you should be sure to include an
 325 explicit call to PKG_PROG_PKG_CONFIG in your configure.ac.
 326
 327 Also note that repeated usage of VARIABLE-PREFIX is not recommended.
 328 After the first successful usage, subsequent calls with the same
 329 VARIABLE-PREFIX will simply use the _LIBS and _CFLAGS variables set from
 330 the previous usage without calling \fIpkg-config\fP again.
 331 .\"
 332 .TP
 333 .I "PKG_PROG_PKG_CONFIG([MIN-VERSION])"
 334
 335 Defines the PKG_CONFIG variable to the best pkg-config available,
 336 useful if you need pkg-config but don't want to use PKG_CHECK_MODULES.
 337 .\"
 338 .TP
 339 .I "PKG_CHECK_EXISTS(MODULES, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])"
 340
 341 Check to see whether a particular set of modules exists.  Similar
 342 to PKG_CHECK_MODULES(), but does not set variables or print errors.
 343
 344 Similar to PKG_CHECK_MODULES, make sure that the first instance of
 345 this or PKG_CHECK_MODULES is called, or make sure to call
 346 PKG_CHECK_EXISTS manually.
 347
 348 .SH METADATA FILE SYNTAX
 349 To add a library to the set of packages \fIpkg-config\fP knows about,
 350 simply install a \fI.pc\fP file. You should install this file to
 351 .I libdir\fP/pkgconfig.
 352 .PP
 353 Here is an example file:
 354 .nf
 355 # This is a comment
 356 prefix=/home/hp/unst   # this defines a variable
 357 exec_prefix=${prefix}  # defining another variable in terms of the first
 358 libdir=${exec_prefix}/lib
 359 includedir=${prefix}/include
 360
 361 Name: GObject                            # human-readable name
 362 Description: Object/type system for GLib # human-readable description
 363 Version: 1.3.1
 364 URL: http://www.gtk.org
 365 Requires: glib-2.0 = 1.3.1
 366 Conflicts: foobar <= 4.5
 367 Libs: -L${libdir} -lgobject-1.3
 368 Libs.private: -lm
 369 Cflags: -I${includedir}/glib-2.0 -I${libdir}/glib/include
 370 .fi
 371 .PP
 372 You would normally generate the file using configure, so that the
 373 prefix, etc. are set to the proper values.  The GNU Autoconf manual
 374 recommends generating files like .pc files at build time rather than
 375 configure time, so when you build the .pc file is a matter of taste
 376 and preference.
 377 .PP
 378 Files have two kinds of line: keyword lines start with a keyword plus
 379 a colon, and variable definitions start with an alphanumeric string
 380 plus an equals sign. Keywords are defined in advance and have special
 381 meaning to \fIpkg-config\fP; variables do not, you can have any
 382 variables that you wish (however, users may expect to retrieve the
 383 usual directory name variables).
 384 .PP
 385 Note that variable references are written "${foo}"; you can escape
 386 literal "${" as "$${".
 387 .TP
 388 .I "Name:"
 389 This field should be a human-readable name for the package. Note that
 390 it is not the name passed as an argument to \fIpkg-config\fP.
 391 .TP
 392 .I "Description:"
 393 This should be a brief description of the package
 394 .TP
 395 .I "URL:"
 396 An URL where people can get more information about and download the package
 397 .TP
 398 .I "Version:"
 399 This should be the most-specific-possible package version string.
 400 .TP
 401 .I "Requires:"
 402 This is a comma-separated list of packages that are required by your
 403 package. Flags from dependent packages will be merged in to the flags
 404 reported for your package. Optionally, you can specify the version
 405 of the required package (using the operators =, <, >, >=, <=);
 406 specifying a version allows \fIpkg-config\fP to perform extra sanity
 407 checks. You may only mention the same package one time on the
 408 .I "Requires:"
 409 line. If the version of a package is unspecified, any version will
 410 be used with no checking.
 411 .TP
 412 .I Requires.private:
 413 A list of packages required by this package. The difference from
 414 .I Requires
 415 is that the packages listed under
 416 .I Requires.private
 417 are not taken into account when a flag list is computed for
 418 dynamically linked executable (i.e., when \-\-static was not
 419 specified).  In the situation where each .pc file corresponds to a
 420 library,
 421 .I Requires.private
 422 shall be used exclusively to specify the dependencies between the
 423 libraries.
 424 .TP
 425 .I "Conflicts:"
 426 This optional line allows \fIpkg-config\fP to perform additional
 427 sanity checks, primarily to detect broken user installations.  The
 428 syntax is the same as
 429 .I "Requires:"
 430 except that
 431 you can list the same package more than once here, for example
 432 "foobar = 1.2.3, foobar = 1.2.5, foobar >= 1.3", if you have reason to
 433 do so. If a version isn't specified, then your package conflicts with
 434 all versions of the mentioned package.
 435 If a user tries to use your package and a conflicting package at the
 436 same time, then \fIpkg-config\fP will complain.
 437 .TP
 438 .I "Libs:"
 439 This line should give the link flags specific to your package.
 440 Don't add any flags for required packages; \fIpkg-config\fP will
 441 add those automatically.
 442 .TP
 443 .I "Libs.private:"
 444 This line should list any private libraries in use.  Private libraries
 445 are libraries which are not exposed through your library, but are
 446 needed in the case of static linking. This differs from
 447 .I Requires.private
 448 in that it references libraries that do not have package files
 449 installed.
 450 .TP
 451 .I "Cflags:"
 452 This line should list the compile flags specific to your package.
 453 Don't add any flags for required packages; \fIpkg-config\fP will
 454 add those automatically.
 455 .\"
 456 .SH AUTHOR
 457
 458 .I pkg-config
 459 was written by James Henstridge, rewritten by Martijn van Beers, and
 460 rewritten again by Havoc Pennington. Tim Janik, Owen Taylor, and Raja
 461 Harinath submitted suggestions and some code.
 462 .I gnome-config
 463 was written by Miguel de Icaza, Raja Harinath and various hackers in
 464 the GNOME team.  It was inspired by Owen Taylor's \fIgtk-config\fP
 465 program.
 466 .\"
 467 .SH BUGS
 468
 469 \fIpkg-config\fP does not handle mixing of parameters with and without
 470 = well.  Stick with one.
 471
 472 Bugs can be reported at http://bugs.freedesktop.org/ under the
 473 .I pkg-config
 474 component.