1pkg-config(1)               General Commands Manual              pkg-config(1)
2
3
4

NAME

6       pkg-config - Return metainformation about installed libraries
7

SYNOPSIS

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

DESCRIPTION

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
24       program: program.c
25            cc program.c $(pkg-config --cflags --libs gnomeui)
26
27       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
35       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
41       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

OPTIONS

46       The following options are supported:
47
48       --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
57       --version
58              Displays the version of pkg-config and terminates.
59
60       --help Displays a help message and terminates.
61
62       --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
74       --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
85       --errors-to-stdout
86              If printing errors, print them to stdout rather than the default
87              stderr
88
89       --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
94
95       The following options are used to compile and link programs:
96
97       --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
105       --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
109       --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
114       --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
119       --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
125       --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
132       --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
140       --print-variables
141              Returns a list of all variables defined in the package.
142
143
144       --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
156       --exists
157
158       --atleast-version=VERSION
159
160       --exact-version=VERSION
161
162       --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
171              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
178       --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
187       --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
192       --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
197       --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
203       --list-all
204              List all modules found in the pkg-config path.
205
206       --print-provides
207              List all modules the given packages provides.
208
209       --print-requires
210              List all modules the given packages requires.
211
212       --print-requires-private
213              List all modules the given packages requires for static  linking
214              (see --static).
215

ENVIRONMENT VARIABLES

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
225       PKG_CONFIG_DEBUG_SPEW
226              If set, causes pkg-config to print all kinds of debugging infor‐
227              mation and report all errors.
228
229       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
238       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
245       PKG_CONFIG_ALLOW_SYSTEM_CFLAGS
246              Don't strip -I/usr/include out of cflags.
247
248       PKG_CONFIG_ALLOW_SYSTEM_LIBS
249              Don't strip -L/usr/lib or -L/lib out of libs.
250
251       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
260       PKG_CONFIG_LIBDIR
261              Replaces   the  default  pkg-config  search  directory,  usually
262              /usr/lib/pkgconfig
263

QUERYING PKG-CONFIG'S DEFAULTS

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

WINDOWS SPECIALITIES

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
278       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

AUTOCONF MACROS

283       PKG_CHECK_MODULES(VARIABLE-PREFIX,  MODULES [,ACTION-IF-FOUND [,ACTION-
284       IF-NOT-FOUND]])
285
286              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
290              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
300              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
305              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
311       PKG_PROG_PKG_CONFIG([MIN-VERSION])
312
313              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
317       PKG_CHECK_EXISTS(MODULES, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])
318
319              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
323              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
327       PKG_INSTALLDIR(DIRECTORY)
328
329              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
335       PKG_NOARCH_INSTALLDIR(DIRECTORY)
336
337              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
343       PKG_CHECK_VAR(VARIABLE,  MODULE,  CONFIG-VARIABLE,   [ACTION-IF-FOUND],
344       [ACTION-IF-NOT-FOUND])
345
346              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
351

METADATA FILE SYNTAX

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
356       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
363       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
373       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
379       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
386       Note that variable references are written "${foo}"; you can escape lit‐
387       eral "${" as "$${".
388
389       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
392       Description:
393              This should be a brief description of the package
394
395       URL:   An URL where people can get more information about and  download
396              the package
397
398       Version:
399              This   should  be  the  most-specific-possible  package  version
400              string.
401
402       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
412       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
421       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
432       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
436       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
443       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

AUTHOR

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

BUGS

456       pkg-config  does  not  handle  mixing  of parameters with and without =
457       well.  Stick with one.
458
459       Bugs can be reported at http://bugs.freedesktop.org/ under the pkg-con‐
460       fig component.
461
462
463
464                                                                 pkg-config(1)
Impressum