[17208] | 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 | .TH pkg-config 1 |
---|
| 6 | .SH NAME |
---|
| 7 | pkg-config \- Return metainformation about installed libraries |
---|
| 8 | .SH SYNOPSIS |
---|
| 9 | .PP |
---|
| 10 | .B pkg-config |
---|
| 11 | [\-\-modversion] [\-\-help] [\-\-print-errors] [\-\-silence-errors] |
---|
| 12 | [\-\-cflags] [\-\-libs] [\-\-libs-only-L] |
---|
| 13 | [\-\-libs-only-l] [\-\-cflags-only-I] |
---|
| 14 | [\-\-variable=VARIABLENAME] |
---|
| 15 | [\-\-define-variable=VARIABLENAME=VARIABLEVALUE] |
---|
| 16 | [\-\-uninstalled] |
---|
| 17 | [\-\-exists] [\-\-atleast-version=VERSION] [\-\-exact-version=VERSION] |
---|
| 18 | [\-\-max-version=VERSION] [LIBRARIES...] |
---|
| 19 | .SH DESCRIPTION |
---|
| 20 | |
---|
| 21 | The \fIpkg-config\fP program is used to retrieve information about |
---|
| 22 | installed libraries in the system. It is typically used to compile |
---|
| 23 | and link against one or more libraries. Here is a typical usage |
---|
| 24 | scenario in a Makefile: |
---|
| 25 | .PP |
---|
| 26 | .nf |
---|
| 27 | program: program.c |
---|
| 28 | cc program.c `pkg-config --cflags --libs gnomeui` |
---|
| 29 | .fi |
---|
| 30 | .PP |
---|
| 31 | |
---|
| 32 | .PP |
---|
| 33 | \fIpkg-config\fP retrieves information about packages from |
---|
| 34 | special metadata files. These files are named after the package, |
---|
| 35 | with the extension \fI.pc\fP. By default, pkg-config looks in |
---|
| 36 | the directory \fIprefix\fP/lib/pkgconfig for these files; it will also |
---|
| 37 | look in the colon-separated (on Windows, semicolon-separated) |
---|
| 38 | list of directories specified by the |
---|
| 39 | PKG_CONFIG_PATH environment variable. |
---|
| 40 | |
---|
| 41 | .PP |
---|
| 42 | The package name specified on the \fIpkg-config\fP command line is |
---|
| 43 | defined to be the name of the metadata file, minus the \fI.pc\fP |
---|
| 44 | extension. If a library can install multiple versions simultaneously, |
---|
| 45 | it must give each version its own name (for example, GTK 1.2 might |
---|
| 46 | have the package name "gtk+" while GTK 2.0 has "gtk+-2.0"). |
---|
| 47 | |
---|
| 48 | .SH OPTIONS |
---|
| 49 | The following options are supported: |
---|
| 50 | .TP |
---|
| 51 | .I "--modversion" |
---|
| 52 | Requests that the version information of the libraries specified on |
---|
| 53 | the command line be displayed. If \fIpkg-config\fP can find all the |
---|
| 54 | libraries on the command line, each library's version string is |
---|
| 55 | printed to stdout, one version per line. In this case \fIpkg-config\fP |
---|
| 56 | exits successfully. If one or more libraries is unknown, |
---|
| 57 | \fIpkg-config\fP exits with a nonzero code, and the contents of stdout |
---|
| 58 | are undefined. |
---|
| 59 | .TP |
---|
| 60 | .I "--help" |
---|
| 61 | Displays a help message and terminates. |
---|
| 62 | |
---|
| 63 | .TP |
---|
| 64 | .I "--print-errors" |
---|
| 65 | If one or more of the modules on the command line, or their |
---|
| 66 | dependencies, are not found, or if an error occurs in parsing a |
---|
| 67 | \fI.pc\fP file, then this option will cause errors explaining the |
---|
| 68 | problem to be printed. With "predicate" options such as "--exists" |
---|
| 69 | \fIpkg-config\fP runs silently by default, because it's usually used |
---|
| 70 | in scripts that want to control what's output. This option can be used |
---|
| 71 | alone (to just print errors encountered locating modules on the |
---|
| 72 | command line) or with other options. The PKG_CONFIG_DEBUG_SPEW |
---|
| 73 | environment variable overrides this option. |
---|
| 74 | |
---|
| 75 | .TP |
---|
| 76 | .I "--silence-errors" |
---|
| 77 | If one or more of the modules on the command line, or their |
---|
| 78 | dependencies, are not found, or if an error occurs in parsing a |
---|
| 79 | \fI.pc\fP file, then this option will keep errors explaining the |
---|
| 80 | problem from being printed. With "predicate" options such as |
---|
| 81 | "--exists" \fIpkg-config\fP runs silently by default, because it's |
---|
| 82 | usually used in scripts that want to control what's output. So this |
---|
| 83 | option is only useful with options such as "--cflags" or |
---|
| 84 | "--modversion" that print errors by default. The PKG_CONFIG_DEBUG_SPEW |
---|
| 85 | environment variable overrides this option. |
---|
| 86 | |
---|
| 87 | .TP |
---|
| 88 | .I "--errors-to-stdout" |
---|
| 89 | If printing errors, print them to stdout rather than the default stderr |
---|
| 90 | |
---|
| 91 | .PP |
---|
| 92 | The following options are used to compile and link programs: |
---|
| 93 | .TP |
---|
| 94 | .I "--cflags" |
---|
| 95 | This prints pre-processor and compile flags required to compile the |
---|
| 96 | packages on the command line, including flags for all their |
---|
| 97 | dependencies. Flags are "compressed" so that each identical flag |
---|
| 98 | appears only once. \fIpkg-config\fP exits with a nonzero code if it |
---|
| 99 | can't find metadata for one or more of the packages on the command |
---|
| 100 | line. |
---|
| 101 | .TP |
---|
| 102 | .I "--libs" |
---|
| 103 | This option is identical to "--cflags", only it prints the link |
---|
| 104 | flags. As with "--cflags", duplicate flags are merged (maintaining |
---|
| 105 | proper ordering), and flags for dependencies are included in the |
---|
| 106 | output. |
---|
| 107 | .TP |
---|
| 108 | .I "--libs-only-L" |
---|
| 109 | This prints the -L/-R part of "--libs". That is, it defines the |
---|
| 110 | library search path but doesn't specify which libraries to link with. |
---|
| 111 | .TP |
---|
| 112 | .I "--libs-only-l" |
---|
| 113 | This prints the -l part of "--libs" for the libraries specified on |
---|
| 114 | the command line. Note that the union of "--libs-only-l" and |
---|
| 115 | "--libs-only-L" may be smaller than "--libs", due to flags such as |
---|
| 116 | -rdynamic. |
---|
| 117 | |
---|
| 118 | .TP |
---|
| 119 | .I "--variable=VARIABLENAME" |
---|
| 120 | This returns the value of a variable defined in a package's \fI.pc\fP |
---|
| 121 | file. Most packages define the variable "prefix", for example, so you |
---|
| 122 | can say: |
---|
| 123 | .nf |
---|
| 124 | $ pkg-config --variable=prefix glib-2.0 |
---|
| 125 | /usr/ |
---|
| 126 | .fi |
---|
| 127 | .TP |
---|
| 128 | .I "--define-variable=VARIABLENAME=VARIABLEVALUE" |
---|
| 129 | This sets a global value for a variable, overriding the value in any |
---|
| 130 | \fI.pc\fP files. Most packages define the variable "prefix", for |
---|
| 131 | example, so you can say: |
---|
| 132 | .nf |
---|
| 133 | $ pkg-config --print-errors --define-variable=prefix=/foo --variable=prefix glib-2.0 |
---|
| 134 | /foo |
---|
| 135 | .fi |
---|
| 136 | |
---|
| 137 | .TP |
---|
| 138 | .I "--uninstalled" |
---|
| 139 | Normally if you request the package "foo" and the package |
---|
| 140 | "foo-uninstalled" exists, \fIpkg-config\fP will prefer the |
---|
| 141 | "-uninstalled" variant. This allows compilation/linking against |
---|
| 142 | uninstalled packages. If you specify the "--uninstalled" option, |
---|
| 143 | \fIpkg-config\fP will return successfully if any "-uninstalled" |
---|
| 144 | packages are being used, and return failure (false) otherwise. |
---|
| 145 | (The "PKG_CONFIG_DISABLE_UNINSTALLED" environment variable keeps |
---|
| 146 | \fIpkg-config\fP from implicitly choosing "-uninstalled" packages, so |
---|
| 147 | if that variable is set, they will only have been used if you pass |
---|
| 148 | a name like "foo-uninstalled" on the command line explicitly.) |
---|
| 149 | |
---|
| 150 | .TP |
---|
| 151 | .I "--exists" |
---|
| 152 | .TP |
---|
| 153 | .I "--atleast-version=VERSION" |
---|
| 154 | .TP |
---|
| 155 | .I "--exact-version=VERSION" |
---|
| 156 | .TP |
---|
| 157 | .I "--max-version=VERSION" |
---|
| 158 | These options test whether the package or list of packages on the |
---|
| 159 | command line are known to \fIpkg-config\fP, and optionally |
---|
| 160 | whether the version number of a package meets certain contraints. |
---|
| 161 | If all packages exist and meet the specified version constraints, |
---|
| 162 | \fIpkg-config\fP exits successfully. Otherwise it exits unsuccessfully. |
---|
| 163 | |
---|
| 164 | Rather than using the version-test options, you can simply give a version |
---|
| 165 | constraint after each package name, for example: |
---|
| 166 | .nf |
---|
| 167 | $ pkg-config --exists 'glib-2.0 >= 1.3.4 libxml = 1.8.3' |
---|
| 168 | .fi |
---|
| 169 | Remember to use \-\-print-errors if you want error messages. |
---|
| 170 | |
---|
| 171 | .TP |
---|
| 172 | .I "--msvc-syntax" |
---|
| 173 | This option is available only on Windows. It causes \fIpkg-config\fP |
---|
| 174 | to output -l and -L flags in the form recognized by the Microsoft |
---|
| 175 | Visual C++ command-line compiler, \fIcl\fP. Specifically, instead of |
---|
| 176 | \fI-Lx:/some/path\fP it prints \fI/libpath:x/some/path\fP, and instead |
---|
| 177 | of \fI-lfoo\fP it prints \fIfoo.lib\fP. Note that the --libs output |
---|
| 178 | consists of flags for the linker, and should be placed on the cl |
---|
| 179 | command line after a /link switch. |
---|
| 180 | |
---|
| 181 | .TP |
---|
| 182 | .I "--dont-define-prefix" |
---|
| 183 | This option is available only on Windows. It prevents \fIpkg-config\fP |
---|
| 184 | from automatically trying to override the value of the variable |
---|
| 185 | "prefix" in each .pc file. |
---|
| 186 | |
---|
| 187 | .TP |
---|
| 188 | .I "--prefix-variable=PREFIX" |
---|
| 189 | Also this option is available only on Windows. It sets the name of the |
---|
| 190 | variable that \fIpkg-config\fP automatically sets as described above. |
---|
| 191 | |
---|
| 192 | .SH ENVIRONMENT VARIABLES |
---|
| 193 | |
---|
| 194 | .TP |
---|
| 195 | .I "PKG_CONFIG_PATH" |
---|
| 196 | A colon-separated (on Windows, semicolon-separated) |
---|
| 197 | list of directories to search for .pc files. |
---|
| 198 | The default directory will always be searched after searching the |
---|
| 199 | path; the default is \fIlibdir\fP/pkgconfig where \fIlibdir\fP |
---|
| 200 | is the libdir where \fIpkg-config\fP was installed. |
---|
| 201 | |
---|
| 202 | .TP |
---|
| 203 | .I "PKG_CONFIG_DEBUG_SPEW" |
---|
| 204 | If set, causes \fIpkg-config\fP to print all kinds of |
---|
| 205 | debugging information and report all errors. |
---|
| 206 | |
---|
| 207 | .TP |
---|
| 208 | .I "PKG_CONFIG_TOP_BUILD_DIR" |
---|
| 209 | A value to set for the magic variable \fIpc_top_builddir\fP |
---|
| 210 | which may appear in \fI.pc\fP files. If the environment variable is |
---|
| 211 | not set, the default value '$(top_builddir)' will be used. This |
---|
| 212 | variable should refer to the top builddir of the Makefile where the |
---|
| 213 | compile/link flags reported by \fIpkg-config\fP will be used. |
---|
| 214 | This only matters when compiling/linking against a package that hasn't |
---|
| 215 | yet been installed. |
---|
| 216 | |
---|
| 217 | .TP |
---|
| 218 | .I "PKG_CONFIG_DISABLE_UNINSTALLED" |
---|
| 219 | Normally if you request the package "foo" and the package |
---|
| 220 | "foo-uninstalled" exists, \fIpkg-config\fP will prefer the |
---|
| 221 | "-uninstalled" variant. This allows compilation/linking against |
---|
| 222 | uninstalled packages. If this environment variable is set, it |
---|
| 223 | disables said behavior. |
---|
| 224 | |
---|
| 225 | .TP |
---|
| 226 | .I "PKG_CONFIG_ALLOW_SYSTEM_CFLAGS" |
---|
| 227 | Don't strip -I/usr/include out of cflags. |
---|
| 228 | |
---|
| 229 | .TP |
---|
| 230 | .I "PKG_CONFIG_ALLOW_SYSTEM_LIBS" |
---|
| 231 | Don't strip -L/usr/lib out of libs |
---|
| 232 | |
---|
| 233 | .SH WINDOWS SPECIALITIES |
---|
| 234 | If a .pc file is found in a directory that matches the usual |
---|
| 235 | conventions (i.e., ends with \\lib\\pkgconfig), the prefix for that |
---|
| 236 | package is assumed to be the grandparent of the directory where the |
---|
| 237 | file was found, and the \fIprefix\fP variable is overridden for that |
---|
| 238 | file accordingly. |
---|
| 239 | |
---|
| 240 | In addition to the \fIPKG_CONFIG_PATH\fP environment variable, the |
---|
| 241 | Registry keys |
---|
| 242 | \fIHKEY_CURRENT_USER\\Software\\pkgconfig\\PKG_CONFIG_PATH\fP and |
---|
| 243 | \fIHKEY_LOCAL_MACHINE\\Software\\pkgconfig\\PKG_CONFIG_PATH\fP can be |
---|
| 244 | used to specify directories to search for .pc files. Each (string) |
---|
| 245 | value in these keys is treated as a directory where to look for .pc |
---|
| 246 | files. |
---|
| 247 | |
---|
| 248 | .SH AUTOCONF MACROS |
---|
| 249 | |
---|
| 250 | .TP |
---|
| 251 | .I "PKG_CHECK_MODULES(VARIABLEBASE,MODULELIST[,ACTION-IF-FOUND,[ACTION-IF-NOT-FOUND]])" |
---|
| 252 | |
---|
| 253 | The macro PKG_CHECK_MODULES can be used in \fIconfigure.in\fP to |
---|
| 254 | check whether modules exist. A typical usage would be: |
---|
| 255 | .nf |
---|
| 256 | PKG_CHECK_MODULES(MYSTUFF, gtk+-2.0 >= 1.3.5 libxml = 1.8.4) |
---|
| 257 | .fi |
---|
| 258 | |
---|
| 259 | This would result in MYSTUFF_LIBS and MYSTUFF_CFLAGS substitution |
---|
| 260 | variables, set to the libs and cflags for the given module list. |
---|
| 261 | If a module is missing or has the wrong version, by default configure |
---|
| 262 | will abort with a message. To replace the default action, |
---|
| 263 | specify an ACTION-IF-NOT-FOUND. PKG_CHECK_MODULES will not print any |
---|
| 264 | error messages if you specify your own ACTION-IF-NOT-FOUND. |
---|
| 265 | However, it will set the variable MYSTUFF_PKG_ERRORS, which you can |
---|
| 266 | use to display what went wrong. |
---|
| 267 | |
---|
[18223] | 268 | If you want to use MYSTUFF_LIBS and MYSTUFF_CFLAGS as Makefile.am |
---|
| 269 | variables (i.e. $(MYSTUFF_LIBS)) then you have to add |
---|
| 270 | AC_SUBST(MYSTUFF_LIBS) to your configure.in so automake can find the |
---|
| 271 | variable. You don't need to do this if you use the @MYSTUFF_LIBS@ |
---|
| 272 | syntax in your Makefile.am instead of $(MYSTUFF_LIBS). |
---|
| 273 | |
---|
[17208] | 274 | .SH METADATA FILE SYNTAX |
---|
| 275 | To add a library to the set of packages \fIpkg-config\fP knows about, |
---|
| 276 | simply install a \fI.pc\fP file. You should install this file to |
---|
| 277 | \fIlibdir\fP/pkgconfig. |
---|
| 278 | |
---|
| 279 | .PP |
---|
| 280 | Here is an example file: |
---|
| 281 | .nf |
---|
| 282 | # This is a comment |
---|
| 283 | prefix=/home/hp/unst # this defines a variable |
---|
| 284 | exec_prefix=${prefix} # defining another variable in terms of the first |
---|
| 285 | libdir=${exec_prefix}/lib |
---|
| 286 | includedir=${prefix}/include |
---|
| 287 | |
---|
| 288 | Name: GObject # human-readable name |
---|
| 289 | Description: Object/type system for GLib # human-readable description |
---|
| 290 | Version: 1.3.1 |
---|
| 291 | Requires: glib-2.0 = 1.3.1 |
---|
| 292 | Conflicts: foobar <= 4.5 |
---|
| 293 | Libs: -L${libdir} -lgobject-1.3 |
---|
| 294 | Cflags: -I${includedir}/glib-2.0 -I${libdir}/glib/include |
---|
| 295 | .fi |
---|
| 296 | |
---|
| 297 | .PP |
---|
| 298 | You would normally generate the file using configure, of course, so |
---|
| 299 | that the prefix, etc. are set to the proper values. |
---|
| 300 | |
---|
| 301 | .PP |
---|
| 302 | Files have two kinds of line: keyword lines start with a keyword plus |
---|
| 303 | a colon, and variable definitions start with an alphanumeric string |
---|
| 304 | plus an equals sign. Keywords are defined in advance and have special |
---|
| 305 | meaning to \fIpkg-config\fP; variables do not, you can have any |
---|
| 306 | variables that you wish (however, users may expect to retrieve the |
---|
| 307 | usual directory name variables). |
---|
| 308 | |
---|
| 309 | .PP |
---|
| 310 | Note that variable references are written "${foo}"; you can escape |
---|
| 311 | literal "${" as "$${". |
---|
| 312 | |
---|
| 313 | .TP |
---|
| 314 | .I "Name:" |
---|
| 315 | This field should be a human-readable name for the package. Note that |
---|
| 316 | it is not the name passed as an argument to \fIpkg-config\fP. |
---|
| 317 | .TP |
---|
| 318 | .I "Description:" |
---|
| 319 | This should be a brief description of the package |
---|
| 320 | .TP |
---|
| 321 | .I "Version:" |
---|
| 322 | This should be the most-specific-possible package version string. |
---|
| 323 | .TP |
---|
| 324 | .I "Requires:" |
---|
| 325 | This is a comma-separated list of packages that are required by your |
---|
| 326 | package. Flags from dependent packages will be merged in to the flags |
---|
| 327 | reported for your package. Optionally, you can specify the version |
---|
| 328 | of the required package (using the operators =, <, >, >=, <=); |
---|
| 329 | specifying a version allows \fIpkg-config\fP to perform extra sanity |
---|
| 330 | checks. You may only mention the same package one time on the |
---|
| 331 | .I "Requires:" |
---|
| 332 | line. If the version of a package is unspecified, any version will |
---|
| 333 | be used with no checking. |
---|
| 334 | .TP |
---|
| 335 | .I "Conflicts:" |
---|
| 336 | This optional line allows \fIpkg-config\fP to perform additional |
---|
| 337 | sanity checks, primarily to detect broken user installations. The |
---|
| 338 | syntax is the same as |
---|
| 339 | .I "Requires:" |
---|
| 340 | except that |
---|
| 341 | you can list the same package more than once here, for example |
---|
| 342 | "foobar = 1.2.3, foobar = 1.2.5, foobar >= 1.3", if you have reason to |
---|
| 343 | do so. If a version isn't specified, then your package conflicts with |
---|
| 344 | all versions of the mentioned package. |
---|
| 345 | If a user tries to use your package and a conflicting package at the |
---|
| 346 | same time, then \fIpkg-config\fP will complain. |
---|
| 347 | .TP |
---|
| 348 | .I "Libs:" |
---|
| 349 | This line should give the link flags specific to your package. |
---|
| 350 | Don't add any flags for required packages; \fIpkg-config\fP will |
---|
| 351 | add those automatically. |
---|
| 352 | |
---|
| 353 | .TP |
---|
| 354 | .I "Cflags:" |
---|
| 355 | This line should list the compile flags specific to your package. |
---|
| 356 | Don't add any flags for required packages; \fIpkg-config\fP will |
---|
| 357 | add those automatically. |
---|
| 358 | |
---|
| 359 | .SH AUTHOR |
---|
| 360 | |
---|
| 361 | \fIpkg-config\fP was written by James Henstridge, rewritten by Martijn |
---|
| 362 | van Beers, and rewritten again by Havoc Pennington. Tim Janik, Owen |
---|
| 363 | Taylor, and Raja Harinath submitted suggestions and some code. |
---|
| 364 | \fIgnome-config\fP was written by Miguel de Icaza, Raja Harinath and |
---|
| 365 | various hackers in the GNOME team. It was inspired by Owen Taylor's |
---|
| 366 | \fIgtk-config\fP program. |
---|
| 367 | |
---|
| 368 | .SH BUGS |
---|
| 369 | Hah! |
---|
| 370 | |
---|
| 371 | |
---|