View Source: pkg-config(1) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages
pkg-config
!!!pkg-config
NAME
SYNOPSIS
DESCRIPTION
OPTIONS
ENVIRONMENT VARIABLES
WINDOWS SPECIALITIES
AUTOCONF MACROS
METADATA FILE SYNTAX
AUTHOR
BUGS
----
!!NAME


pkg-config - Return metainformation about installed libraries
!!SYNOPSIS


__pkg-config__ [[--modversion] [[--help] [[--print-errors]
[[--silence-errors] [[--cflags] [[--libs] [[--libs-only-L]
[[--libs-only-l] [[--cflags-only-I] [[--variable=VARIABLENAME]
[[--define-variable=VARIABLENAME=VARIABLEVALUE]
[[--uninstalled] [[--exists] [[--atleast-version=VERSION]
[[--exact-version=VERSION] [[--max-version=VERSION]
[[LIBRARIES...]
!!DESCRIPTION


The ''pkg-config'' program is used to retrieve
information about installed libraries in the system. It is
typically used to compile and link against one or more
libraries. Here is a typical usage scenario 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 are named after the
package, with the extension ''.pc''. By default,
pkg-config looks in the directory
''prefix''/lib/pkgconfig for these files; it will also
look in the colon-separated (on Windows,
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, minus
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
''
!!OPTIONS


The following options are supported:


''--modversion''


Requests that the version information of the libraries
specified on the command line be displayed. If
''pkg-config'' can find all 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.


''--help''


Displays a help message and terminates.


''--print-errors''


If one or more of the modules on the command line, or their
dependencies, are not found, or if an error occurs in
parsing a problem to be printed. With
pkg-config'' runs
silently by default, because it's usually used in scripts
that want to control what's output. 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''


If one or more of the modules on the command line, or their
dependencies, are not found, or if an error occurs in
parsing a problem from being printed. With
pkg-config'' runs silently by default, because it's
usually used in scripts that want to control what's output.
So this option is only useful with options such as
''


''--errors-to-stdout''


If printing errors, print them to stdout rather than the
default stderr


The following options are used to compile and link
programs:


''--cflags''


This prints pre-processor and compile flags required to
compile the packages on the command line, including flags
for all their dependencies. Flags are
pkg-config'' exits with a nonzero code if it can't find
metadata for one or more of the packages on the command
line.


''--libs''


This option is identical to


''--libs-only-L''


This prints the -L/-R part of


''--libs-only-l''


This prints the -l part of


''--variable=VARIABLENAME''


This returns the value of a variable defined in a package's
''.pc'' file. Most packages define the variable
''


  $ pkg-config --variable=prefix glib-2.0
/usr/


''--define-variable=VARIABLENAME=VARIABLEVALUE''


This sets a global value for a variable, overriding the
value in any example, so you can say:


  $ pkg-config --print-errors --define-variable=prefix=/foo --variable=prefix glib-2.0
/foo


''--uninstalled''


Normally if you request the package
pkg-config'' will prefer the
''pkg-config'' will return successfully if any
''pkg-config'' from implicitly choosing
''


''--exists''


''--atleast-version=VERSION''


''--exact-version=VERSION''


''--max-version=VERSION''


These options test whether the package or list of 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 it exits
unsuccessfully.


Rather than using the version-test options, you can simply
give a version constraint after each package name, for
example:


  $ pkg-config --exists 'glib-2.0
Remember to use --print-errors if you want error messages.


''--msvc-syntax''


This option is available only on Windows. It causes
''pkg-config'' to output -l and -L flags in the form
recognized by the Microsoft Visual C++ command-line
compiler, ''cl''. Specifically, instead of
''-Lx:/some/path'' it prints ''/libpath:x/some/path'',
and instead of ''-lfoo'' it prints ''foo.lib''. Note
that the --libs output consists of flags for the linker, and
should be placed on the cl command line after a /link
switch.


''--dont-define-prefix''


This option is available only on Windows. It prevents
''pkg-config'' from automatically trying to override the
value of the variable
''


''--prefix-variable=PREFIX''


Also this option is available only on Windows. It sets the
name of the variable that ''pkg-config'' automatically
sets as described above.
!!ENVIRONMENT VARIABLES


''PKG_CONFIG_PATH''


A colon-separated (on Windows, semicolon-separated) list of
directories to search for .pc files. The default directory
will always be searched after searching the path; the
default is ''libdir''/pkgconfig where ''libdir'' is
the libdir where ''pkg-config'' was
installed.


''PKG_CONFIG_DEBUG_SPEW''


If set, causes ''pkg-config'' to print all kinds of
debugging information and report all errors.


''PKG_CONFIG_TOP_BUILD_DIR''


A value to set for the magic variable ''pc_top_builddir''
which may appear in ''.pc'' files. If the environment
variable is not set, the default value '$(top_builddir)'
will be used. This variable should refer to the top builddir
of the Makefile where the compile/link flags reported by
''pkg-config'' will be used. This only matters when
compiling/linking against a package that hasn't yet been
installed.


''PKG_CONFIG_DISABLE_UNINSTALLED''


Normally if you request the package
pkg-config'' will prefer the
''


''PKG_CONFIG_ALLOW_SYSTEM_CFLAGS''


Don't strip -I/usr/include out of cflags.


''PKG_CONFIG_ALLOW_SYSTEM_LIBS''


Don't strip -L/usr/lib out of libs
!!WINDOWS SPECIALITIES


If a .pc file is found in a directory that matches the usual
conventions (i.e., ends with libpkgconfig), the prefix for
that package is assumed to be the grandparent of the
directory where 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_USERSoftwarepkgconfigPKG_CONFIG_PATH'' and
''HKEY_LOCAL_MACHINESoftwarepkgconfigPKG_CONFIG_PATH''
can be used to specify directories to search for .pc files.
Each (string) value in these keys is treated as a directory
where to look 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. A
typical usage would be:


 PKG_CHECK_MODULES(MYSTUFF, gtk+-2.0
This would result in MYSTUFF_LIBS and MYSTUFF_CFLAGS substitution variables, set to the libs and cflags 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, specify 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 display what went wrong.
!!METADATA FILE SYNTAX


To add a library to the set of packages ''pkg-config''
knows about, simply install a ''.pc'' file. You should
install this file to ''libdir''/pkgconfig.


Here is an example file:


# This is a comment
prefix=/home/hp/unst   # 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


You would normally generate the file using configure, of
course, so that the prefix, etc. are set to the proper
values.


Files have two kinds of line: keyword lines start with a
keyword plus a colon, and variable definitions start with an
alphanumeric string plus an equals sign. Keywords are
defined in advance and have special meaning to
''pkg-config''; variables do not, you can have any
variables that you wish (however, users may expect to
retrieve the usual directory name variables).


Note that variable references are written


''Name:''


This field should be a human-readable name for the package.
Note that it is not the name passed as an argument to
''pkg-config''.


''Description:''


This should be a brief description of the
package


''Version:''


This should be the most-specific-possible package version
string.


''Requires:''


This is 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 =,
pkg-config'' to perform
extra sanity checks. You may only mention the same package
one time on the ''Requires:'' line. If the version of a
package is unspecified, any version will be used with no
checking.


''Conflicts:''


This optional line 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
here, for example
''pkg-config'' will complain.


''Libs:''


This line should give the link flags specific to your
package. Don't add any flags for required packages;
''pkg-config'' will add those automatically.


''Cflags:''


This line should list the compile flags specific to your
package. Don't add any flags for required packages;
''pkg-config'' will add those automatically.
!!AUTHOR


''pkg-config'' was written by James Henstridge, rewritten
by Martijn van Beers, and rewritten again by Havoc
Pennington. Tim Janik, Owen Taylor, and Raja Harinath
submitted suggestions and some code. ''gnome-config'' was
written by Miguel de Icaza, Raja Harinath and various
hackers in the GNOME team. It was inspired by Owen Taylor's
''gtk-config'' program.
!!BUGS


Hah!
----
One page links to pkg-config(1):
Man1p
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Last edited on Monday, June 3, 2002 6:50:55 pm by "perry"
Edit PageHistory Diff Info LikePages