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