pkg-config

[Havoc Pennington <hp redhat com>]

Hi,

I've been rewriting pkg-config in C, which makes it a _lot_ faster
(and easier to add features to). Should perk up everyone's
configure.in.

I have .pc files already for glib thru gtk+, and pkg-config can invoke
gnome-config for packages it doesn't understand natively. This means
apps can start using it without requiring new library releases.

So, want to look at going ahead and migrating to this for most
packages, certainly for GTK since GTK was previously using glib-config
and gtk-config and the addition of gdk-pixbuf etc. is complicating
that.

The C pkg-config is basically the same as gnome-config and the sh
pkg-config that have already been discussed at some length.
Notable differences:

 - The .pc file is now a defined format rather than a shell script

 - there aren't options to get the install dirs of a package, instead
   you can just retrieve arbitrary variables from the .pc file, and 
   some variables like "prefix" have a conventional meaning.
   We can add all the install dirs if people are using that 
   feature (though typical uses I've seen are broken - packages 
   end up installing stuff outside their own prefix, which prevents
   home-dir installs and is just in general wrong). Would appreciate 
   pointers to sample uses of this feature.

 - I didn't implement "self" vs. "system" libs because I couldn't 
   figure out the purpose of this feature. The invariant pkg-config 
   maintains is that each library appears after any libraries that 
   depend on it in the link flags. AFAIK this always produces 
   correct results.

 - added nice options --exists, --atleast-version, etc. to help avoid
   .m4 macros.

 - additional automatic error checking via versioned Requires: and
   Conflicts: fields

Appending a pkg-config man page; this explains the .pc file syntax and
the options pkg-config has.

An example usage from configure.in:
 
# Check glib

AC_MSG_CHECKING(GLib flags)
if $PKG_CONFIG --atleast-version=1.3.1 glib-2.0 ; then
        GLIB_CFLAGS=`$PKG_CONFIG --cflags glib-2.0`
        GLIB_LIBS=`$PKG_CONFIG --libs glib-2.0`
        AC_SUBST(GLIB_LIBS)
        AC_SUBST(GLIB_CFLAGS)

        AC_MSG_RESULT($GLIB_CFLAGS $GLIB_LIBS)
else
        AC_MSG_ERROR([
*** GLib not found. GLib is required to build Inti.
])
fi        

Of course we can provide m4 for that, as desired.

Havoc

.\" 
.\" pkg-config manual page.
.\" (C) Red Hat, Inc. based on gnome-config man page (C) Miguel de Icaza (miguel@gnu.org)
.\"
.TH pkg-config 1
.SH NAME
pkg-config \- Return metainformation about installed libraries
.SH SYNOPSIS
.PP
.B pkg-config
[\-\-modversion] [\-\-help] [\-\-cflags] [\-\-libs] [\-\-libs-only-L]
[\-\-libs-only-l] [\-\-cflags-only-I] [\-\-variable=VARIABLENAME]
[\-\-exists] [\-\-atleast-version=VERSION] [\-\-exact-version=VERSION]
[\-\-max-version=VERSION] [LIBRARIES...]
.SH DESCRIPTION

The \fIpkg-config\fP 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:
.PP
.nf
program: program.c
	cc program.c `pkg-config --cflags --libs gnomeui`
.fi
.PP

.PP
\fIpkg-config\fP retrieves information about packages from 
special metadata files. These files are named after the package, 
with the extension \fI.pc\fP. By default, pkg-config looks in 
the directory \fIprefix\fP/lib/pkgconfig for these files; it will also
look in the list of directories specified by the PKG_CONFIG_PATH
environment variable. 

.PP
The package name specified on the \fIpkg-config\fP command line is
defined to be the name of the metadata file, minus the \fI.pc\fP
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 "gtk+-2.0").

.SH OPTIONS
The following options are supported:
.TP
.I "--modversion"
Requests that the version information of the libraries specified on
the command line be displayed.  If \fIpkg-config\fP 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 \fIpkg-config\fP
exits successfully. If one or more libraries is unknown,
\fIpkg-config\fP exits with a nonzero code, and the contents of stdout
are undefined.
.TP
.I "--help"
Displays a help message and terminates.
.PP
The following options are used to compile and link programs:
.TP
.I "--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 "compressed" so that each identical flag
appears only once. \fIpkg-config\fP exits with a nonzero code if it
can't find metadata for one or more of the packages on the command
line.
.TP 
.I "--libs"
This option is identical to "--cflags", only it prints the link
flags. As with "--cflags", duplicate flags are merged (maintaining
proper ordering), and flags for dependencies are included in the
output.
.TP
.I "--libs-only-L"
This prints the -L/-R part of "--libs". That is, it defines the 
library search path but doesn't specify which libraries to link with.
.TP
.I "--libs-only-l"
This prints the -l part of "--libs" for the libraries specified on
the command line. Note that the union of "--libs-only-l" and
"--libs-only-L" may be smaller than "--libs", due to flags such as
-rdynamic.

.TP
.I "--variable=VARIABLENAME"
This returns the value of a variable defined in a package's \fI.pc\fP
file. Most packages define the variable "prefix", for example, so you 
can say:
.nf
  $ pkg-config --variable=prefix gtk+
  /usr/
.fi

.TP
.I "--exists"
.TP
.I "--atleast-version=VERSION"
.TP
.I "--exact-version=VERSION"
.TP
.I "--max-version=VERSION"
These options test whether the package or list of packages on the
command line are known to \fIpkg-config\fP, and optionally 
whether the version number of a package meets certain contraints.
If all packages exist and meet the specified version constraints,
\fIpkg-config\fP exits successfully. Otherwise it exits unsuccessfully.

.SH METADATA FILE SYNTAX
To add a library to the set of packages \fIpkg-config\fP knows about,
simply install a \fI.pc\fP file. You should install this file to 
\fIlibdir\fP/pkgconfig.

.PP
Here is an example file:
.nf
# 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 <= 4.5
Libs: -L${libdir} -lgobject-1.3
Cflags: -I${includedir}/glib-2.0 -I${libdir}/glib/include 
.fi

.PP
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 \fIpkg-config\fP; variables do not, you can have any
variables that you wish (however, users may expect to retrieve the
usual directory name variables).

.PP
Note that variable references are written "${foo}"; you can escape
literal "${" as "$${".

.TP
.I "Name:"
This field should be a human-readable name for the package. Note that
it is not the name passed as an argument to \fIpkg-config\fP.
.TP
.I "Description:"
This should be a brief description of the package
.TP
.I "Version:"
This should be the most-specific-possible package version string.
.TP
.I "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 =, <, >, >=, <=);
specifying a version allows \fIpkg-config\fP to perform extra sanity
checks. You may only mention the same package one time on the 
.I "Requires:"
line. If the version of a package is unspecified, any version will
be used with no checking.
.TP
.I "Conflicts:"
This optional line allows \fIpkg-config\fP to perform additional
sanity checks, primarily to detect broken user installations.  The
syntax is the same as
.I "Requires:"
except that
you can list the same package more than once here, for example 
"foobar = 1.2.3, foobar = 1.2.5, foobar >= 1.3", if you have reason to
do so. If a version isn't specified, then 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, then \fIpkg-config\fP will complain.
.TP
.I "Libs:"
This line should give the link flags specific to your package. 
Don't add any flags for required packages; \fIpkg-config\fP will 
add those automatically.

.TP
.I "Cflags:"
This line should list the compile flags specific to your package. 
Don't add any flags for required packages; \fIpkg-config\fP will 
add those automatically.

.SH AUTHOR

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

.SH BUGS
Hah!