pkg-config(1) User Commands pkg-config(1)
NAME
pkg-config - return meta information about installed libraries
SYNOPSIS
pkg-config [--modversion] [--help] [--print-errors] [--silence-errors] [--cflags] [--libs] [--libs-only-L] [--libs-only-l] [--cflags-only-
I] [--variable=variable_name] [--define-variable=variable_name=variable_value] [--uninstalled] [--exists] [--atleast-version=version]
[--exact-version=version] [--max-version=version] [libraries]
DESCRIPTION
pkg-config retrieves information about installed libraries in the system. pkg-config is typically used to compile and link against one or
more libraries. The following example shows how to use pkg-config in a Makefile:
program: program.c
cc program.c `pkg-config --cflags --libs gnomeui`
pkg-config retrieves information about packages from special metadata files. These files have the same name as the package, with the exten-
sion .pc. By default, pkg-config looks in the directory /usr/lib/pkgconfig for these files. It also looks in the colon-separated (on Win-
dows, semicolon-separated) list of directories specified by the PKG_CONFIG_PATH environment variable.
The package name specified on the pkg-config command line is defined to be the name of the metadata file, without the .pc extension. If a
library can install multiple versions simultaneously, it must give each version its own name. For example, GTK 1.2 might have the package
name gtk+ while GTK 2.0 has the package name gtk+-2.0.
EXTENDED DESCRIPTION
A .pc file has two kinds of line:
o Keyword lines start with a keyword and a colon.
o Variable definitions start with an alphanumeric string and an equals sign.
Keywords are defined in advance and have special meaning to pkg-config. Variables do not have special meaning, you can specify any vari-
ables that you wish. However, users may expect to retrieve the usual directory name variables.
Note that variable references are written "${foo}"; you can escape literal "${" as "$${".
pkg-config supports the following keywords:
Name A human-readable name for the package. Note that it is not the name passed as an argument to pkg-config.
Description A brief description of the package.
Version The most-specific-possible package version string.
Requires A comma-separated list of packages that are required by your package. Flags from dependent packages will be merged
in to the flags reported for your package. Optionally, you can specify the version of the required package (using
the operators =, <, >, >=, <=). Specifying a version allows pkg-config to perform extra sanity checks. You may only
mention the same package once on the Requires: line. If the version of a package is not specified, any version will
be used with no checking.
Conflicts Optional. Allows pkg-config to perform additional sanity checks, primarily to detect broken user installations.
The syntax is the same as Requires: except that you can list the same package more than once, for example "foobar =
1.2.3, foobar = 1.2.5, foobar >= 1.3", if you have reason to do so. If a version is not specified, your package
conflicts with all versions of the mentioned package. If a user tries to use your package and a conflicting package
at the same time, pkg-config complains.
Libs The link flags specific to your package. Do not add any flags for required packages, pkg-config adds these automat-
ically.
Cflags The compile flags specific to your package. Do not add any flags for required packages, pkg-config adds these auto-
matically.
See the EXAMPLES section below for a sample .pc file.
Windows Specialities
If a .pc file is found in a directory that ends with /lib/pkgconfig, the prefix for that package is assumed to be the grandparent of the
directory in which the file was found, and the prefix variable is overridden for that file accordingly.
In addition to the PKG_CONFIG_PATH environment variable, the Registry keys HKEY_CURRENT_USERSoftwarepkg-configPKG_CONFIG_PATH and
HKEY_LOCAL_MACHINESoftwarepkg-configPKG_CONFIG_PATH can be used to specify directories to search for .pc files. Each string value in
these keys is treated as a directory in which to search for .pc files.
autoconf Macros
PKG_CHECK_MODULES(variablebase,modulelist[,action-if-found,[action-if-not-found]])
The macro PKG_CHECK_MODULES can be used in configure.in to check whether modules exist, as shown in the following example:
PKG_CHECK_MODULES(MYSTUFF, gtk+-2.0 >= 1.3.5 libxml = 1.8.4)
In this example, the MYSTUFF_LIBS and MYSTUFF_CFLAGS substitution variables are set to the libs and cflags values for the given module
list. If a module is missing or has the wrong version, by default configure will abort with a message. To replace the default action, spec-
ify an ACTION-IF-NOT-FOUND. PKG_CHECK_MODULES will not print any error messages if you specify your own ACTION-IF-NOT-FOUND. However, it
will set the variable MYSTUFF_PKG_ERRORS, which you can use to find out what went wrong.
Compiling 64-Bit Binaries
To compile 64-bit binaries, pkg-config must use metadata files that specify the flags for the 64-bit libraries. To ensure that pkg-config
can find the metadata files for 64-bit libraries, set the PKG_CONFIG_PATH environment variable to /usr/lib/64/pkgconfig/ when compiling
64-bit software.
OPTIONS
The following options are supported:
--atleast-version=version
See the entry for the --exists option.
--cflags
Prints pre-processor and compile flags required to compile the packages on the command line, including flags for all their dependen-
cies. Flags are "compressed" so that each identical flag appears only once. pkg-config exits with a nonzero code if it cannot find
metadata for one or more of the packages on the command line.
--define-variable=variablename=variablevalue
Sets a global value for a variable, overriding the value in any example. For example:
$ pkg-config --print-errors --define-variable=prefix=/foo
--variable=prefix glib-2.0 /foo
--dont-define-prefix
Available only on Windows. This option prevents pkg-config from automatically trying to override the value of the variable prefix in
each .pc file.
--errors-to-stdout
If printing errors, print them to stdout rather than the default stderr.
--exact-version=version
See the entry for the --exists option.
--exists
The --exists, --atleast-version=version, --exact-version=version, and --max-version=version options test whether the packages on the
command line are known to pkg-config, and optionally whether the version number of a package meets certain contraints. If all packages
exist and meet the specified version constraints, pkg-config exits successfully. Otherwise, pkg-config exits unsuccessfully. Rather
than using the version-test options, you can simply give a version constraint after each package name, as shown in the following exam-
ple:
$ pkg-config --exists 'glib-2.0 >= 1.3.4 libxml = 1.8.3'
Remember to use the --print-errors option if you want to display error messages.
--help
Displays a help message and terminates.
--libs
Identical to --cflags option but only prints the link flags. Duplicate flags are merged, maintaining proper ordering, and flags for
dependencies are included in the output.
--libs-only-L
Prints the -L/-R part of the --libs option. That is, it defines the library search path but does not specify which libraries to link
with.
--libs-only-l
Prints the -l part of the --libs option for the libraries specified on the command line. Note that the union of the --libs-only-l and
--libs-only-L options may be smaller than the --libs option, due to flags such as -rdynamic.
--max-version=version
See the entry for the --exists option.
--modversion
Requests that the version information of the libraries specified on the command line be displayed. If pkg-config can find all of the
libraries on the command line, each library's version string is printed to stdout, one version per line. In this case pkg-config exits
successfully. If one or more libraries is unknown, pkg-config exits with a nonzero code, and the contents of stdout are undefined.
--msvc-syntax
Available only on Windows. This option causes pkg-config to output -l and -L flags in the form recognized by the Microsoft Visual C++
command-line compiler, cl, as follows:
o Prints /libpath:x/some/path instead of -Lx:/some/path
o Prints foo.lib instead of -lfoo
Note that the --libs output consists of flags for the linker, and should be placed on the cl command line after a /link switch.
--prefix-variable=prefix
Available only on Windows. This option sets the name of the variable that pkg-config automatically sets as described above.
--print-errors
Displays an error if one or more of the modules on the command line, or their dependencies, are not found, or if an error occurs in
parsing. This option can be used alone to just print errors encountered locating modules on the command line, or with other options.
The PKG_CONFIG_DEBUG_SPEW environment variable overrides this option.
--silence-errors
Does not display an error if one or more of the modules on the command line, or their dependencies, are not found, or if an error
occurs in parsing. With predicate options such as --exists, pkg-config runs silently by default, because it is usually used in scripts
that want to control what is output. This option is only useful with options that print errors by default, such as --cflags or --mod-
version. The PKG_CONFIG_DEBUG_SPEW environment variable overrides this option.
--uninstalled
Normally, if you request the package foo and the package foo-uninstalled exists, pkg-config will prefer the uninstalled variant. This
allows compilation/linking against uninstalled packages. If you specify the --uninstalled option, pkg-config returns successfully if
any uninstalled packages are being used. Otherwise, pkg-config fails. The PKG_CONFIG_DISABLE_UNINSTALLED environment variable prevents
pkg-config from implicitly choosing uninstalled packages. If the PKG_CONFIG_DISABLE_UNINSTALLED variable is set, uninstalled packages
are used only if you explicitly pass a name such as foo-uninstalled on the command line.
--variable=variablename
Returns the value of a variable defined in a package's .pc file. For example, most packages define the variable prefix:
$ pkg-config --variable=prefix glib-2.0 /usr/
ENVIRONMENT VARIABLES
See environ(5) for descriptions of environment variables.
PKG_CONFIG_ALLOW_SYSTEM_CDoAnot strip -I/usr/include from cflags.
PKG_CONFIG_ALLOW_SYSTEM_DoBnot strip -L/usr/lib from libs.
PKG_CONFIG_DEBUG_SPEW If set, causes pkg-config to print all debugging information and report all errors.
PKG_CONFIG_DISABLE_UNINSTNormally, if you request the package foo and the package foo-uninstalled exists, pkg-config prefers the unin-
stalled variant. This allows compilation/linking against uninstalled packages. If the PKG_CONFIG_DISABLE_UNIN-
STALLED environment variable is set, pkg-config prefers the installed variant.
PKG_CONFIG_PATH A colon-separated (on Windows, semicolon-separated) list of directories to search for .pc files. The default direc-
tory is always searched after searching the path specified by PKG_CONFIG_PATH. The default value of PKG_CON-
FIG_PATH is libdir/pkgconfig, where libdir is the lib directory where pkg-config is installed. On Solaris systems,
libdir is /usr/lib.
PKG_CONFIG_TOP_BUILD_DIRSets the value of the magic variable pc_top_builddir, which may appear in .pc files. If this environment variable
is not set, the default value '$(top_builddir)' is used. The PKG_CONFIG_TOP_BUILD_DIR variable should refer to the
top builddir of the Makefile where the compile/link flags reported by pkg-config are used. The PKG_CON-
FIG_TOP_BUILD_DIR variable is only used when compiling/linking against a package that has not yet been installed.
EXAMPLES
Example 1: Example .pc File
Here is an example .pc file:
# This is a comment
prefix=/usr # this defines a variable
exec_prefix=${prefix} # defining another variable in terms of the first
libdir=${exec_prefix}/lib
includedir=${prefix}/include
Name: GObject# human-readable name
Description: Object/type system for GLib # human-readable description
Version: 1.3.1
Requires: glib-2.0 = 1.3.1
Conflicts: foobar <= 4.5
Libs: -L${libdir} -lgobject-1.3
Cflags: -I${includedir}/glib-2.0 -I${libdir}/glib/include
Example 2: Adding a Library to the Set of Packages Known to pkg-config
To add a library to the set of packages known to pkg-config, you must install the library-specific .pc file in the /usr/lib/pkgconfig
directory.
If the .pc file does not exist, generate the file by running the configure command. Generating the file in this way ensures that the prefix
and other variables are set to the correct values.
Example 3: Getting the Compile Flags Required for the gnomeui Package
example% pkg-config --cflags libgnomeui-2.0
FILES
The following files are used by this application:
/usr/bin/pkg-config Executable for installed library helper script
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Availability |SUNWgnome-common-devel |
+-----------------------------+-----------------------------+
|Interface stability |External |
+-----------------------------+-----------------------------+
SEE ALSO
Latest version of the GNOME Desktop User Guide for your platform.
NOTES
Updated by Brian Cameron, Sun Microsystems Inc., 2003, 2004. Written by James Henstridge, Martijn van Beers, Havoc Pennington, Tim Janik,
Owen Taylor, Raja Harinath, Miguel de Icaza.
SunOS 5.10 15 Jul 2004 pkg-config(1)