Documentation about gtk-config and AM_PATH_GTK
This commit is contained in:
Owen Taylor
193
docs/gtk-config.txt
Normal file
193
docs/gtk-config.txt
Normal file
@ -0,0 +1,193 @@
|
||||
CONFIGURING PACKAGES TO WORK WITH GTK
|
||||
-------------------------------------
|
||||
|
||||
Compiling a program succesfully against the GTK, GDK, and GLIB
|
||||
libraries can require a large number of command line options
|
||||
to your compiler and linker that are hard to guess correctly.
|
||||
The additional libraries required may, for example, depend on the
|
||||
manner which GTK was configured
|
||||
|
||||
Several tools are included in this package to make process
|
||||
easier.
|
||||
|
||||
First, there is the shell script 'gtk-config' (installed in
|
||||
$exec_prefix/bin):
|
||||
|
||||
Invoking gtk-config
|
||||
-------------------
|
||||
|
||||
gtk-config can be invoked in one of three forms:
|
||||
|
||||
gtk-config --version
|
||||
Prints out the version of GTK installed
|
||||
|
||||
gtk-config --cflags
|
||||
Prints '-I' flags pointing to the installed d
|
||||
|
||||
gtk-config --libs
|
||||
Prints out the linker flags necessary to link a program against GTK
|
||||
|
||||
|
||||
Example of using gtk-config
|
||||
---------------------------
|
||||
|
||||
Typically, gtk-config will be used within a configure script,
|
||||
as described below. It, however, can also be used directly
|
||||
from the command line to compile a simple program. For example:
|
||||
|
||||
cc -o simple `gtk-config --cflags` simple.c `gtk-config --libs`
|
||||
|
||||
This command line might expand to (for example):
|
||||
|
||||
cc -o simple -I/usr/local/lib/glib/include -I/usr/local/include \
|
||||
-I/usr/X11R6/include simple.c -L/usr/local/lib -L/usr/X11R6/lib \
|
||||
-lgtk -lgdk -lglib -lXi -lXext -lX11 -lm
|
||||
|
||||
Not only is the form using gtk-config easier to type, it will
|
||||
work on any system, no matter how GTK was configured.
|
||||
|
||||
|
||||
AM_PATH_GTK
|
||||
-----------
|
||||
|
||||
For packages configured using GNU automake, GTK also provides
|
||||
a macro to automate the process of running GTK.
|
||||
|
||||
AM_PATH_GTK([MINIMUM-VERSION, [ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]])
|
||||
|
||||
This macro:
|
||||
|
||||
* Determines the location of GTK using gtk-config, which is either
|
||||
found in the user's path, or from the environment variable
|
||||
GTK_CONFIG
|
||||
|
||||
* Tests the installed libraries to make sure that there version
|
||||
is later than MINIMUM-VERSION. (A default version will be used
|
||||
if not specified)
|
||||
|
||||
* If the required version was found, sets the GDK_CFLAGS variable to
|
||||
the output of `gtk-config --cflags` and the GDK_LIBS variable to
|
||||
the output of `gtk-config --libs`, and calls AC_SUBST() for these
|
||||
variables so they can be used in generated makefiles, and then
|
||||
executes ACTION-IF-FOUND.
|
||||
|
||||
* If the required version was not found, sets GDK_CFLAGS and GDK_LIBS
|
||||
to empty strings, and executes ACTION-IF-NOT-FOUND.
|
||||
|
||||
This macro is in file 'gtk.m4' which is installed in $datadir/aclocal.
|
||||
Note that if automake was installed with a different --prefix than
|
||||
GTK, you will either have to manually move gtk.m4 to automake's
|
||||
$datadir/aclocal, or give aclocal the -I option when running it.
|
||||
|
||||
|
||||
Configuring a package that uses AM_PATH_GTK
|
||||
-------------------------------------------
|
||||
|
||||
Simply make sure that gtk-config is in your path, and run
|
||||
the configure script.
|
||||
|
||||
Notes:
|
||||
|
||||
* You can also specify a gtk-config not in your path by
|
||||
setting the GTK_CONFIG environment variable to the
|
||||
name of the executable
|
||||
|
||||
* If you move the GTK package from its installed location,
|
||||
you will need either need to modify gtk-config script
|
||||
manually to point to the new location or rebuild GTK.
|
||||
|
||||
[ As a future enhancement AM_PATH_GTK should support options
|
||||
to override the default locations found in gtk-config ]
|
||||
|
||||
|
||||
Example of a package using AM_PATH_GTK
|
||||
--------------------------------------
|
||||
|
||||
The following shows how to build a simple package using automake
|
||||
and the AM_PATH_GTK macro. The program used here is the testinput.c
|
||||
|
||||
You should first read the introductory portions of the automake
|
||||
Manual, if you are not already familiar with it.
|
||||
|
||||
Two files are needed, 'configure.in', which is used to build the
|
||||
configure script:
|
||||
|
||||
==configure.in===
|
||||
dnl Process this file with autoconf to produce a configure script.
|
||||
AC_INIT(testinput.c)
|
||||
|
||||
AM_INIT_AUTOMAKE(testinput.c, 1.0.0)
|
||||
|
||||
AC_PROG_CC
|
||||
AM_PROG_CC_STDC
|
||||
AC_PROG_INSTALL
|
||||
|
||||
AM_PATH_GTK(0.99.5,
|
||||
[LIBS="$LIBS $GTK_LIBS"
|
||||
CFLAGS="$CFLAGS $GTK_CFLAGS"],
|
||||
AC_MSG_ERROR(Cannot find GTK: Is gtk-config in path?))
|
||||
|
||||
AC_OUTPUT(Makefile)
|
||||
=================
|
||||
|
||||
The only command in this which is not standard for automake
|
||||
is the AM_PATH_GTK() macro.
|
||||
|
||||
That command does the following:
|
||||
|
||||
If a GTK version greater than 0.99.5 is found, adds $GTK_LIBS to
|
||||
$LIBS and $GTK_CFLAGS to $CFLAGS. Otherwise, dies with the error
|
||||
message "Cannot find GTK: Is gtk-config in path?"
|
||||
|
||||
And the 'Makefile.am', which will be used to build the Makefile.
|
||||
|
||||
== Makefile.am ==
|
||||
bin_PROGRAMS = testinput
|
||||
testinput_SOURCES = testinput.c
|
||||
=================
|
||||
|
||||
This Makefile.am, says that we are building a single executable,
|
||||
from a single sourcefile 'testinput.c'. Since every program
|
||||
we are building uses GTK we simply added the GTK options
|
||||
to $LIBS and $CFLAGS, but in other circumstances, we might
|
||||
want to specify them on a per-program basis: for instance by
|
||||
adding the lines:
|
||||
|
||||
testinput_LDADD = $(GTK_LIBS)
|
||||
INCLUDES = $(GTK_CFLAGS)
|
||||
|
||||
to the Makefile.am.
|
||||
|
||||
To try this example out, create a new directory, add the two
|
||||
files above two it, and copy the testinput.c file from
|
||||
the gtk/ subdirectory to the new directory. Edit the line:
|
||||
|
||||
#include "gtk.h"
|
||||
|
||||
in testgtk.c, to read:
|
||||
|
||||
#include <gtk/gtk.h>
|
||||
|
||||
|
||||
Now execute the following commands:
|
||||
|
||||
automake --add-missing
|
||||
aclocal
|
||||
autoconf
|
||||
|
||||
You now have a package that can be built in the normal fashion
|
||||
|
||||
./configure
|
||||
make
|
||||
make install
|
||||
|
||||
|
||||
Notes:
|
||||
|
||||
* If you are converting a package that used a pre-1.0 version of
|
||||
GTK, you should remove the autoconf tests for X. The results
|
||||
of these tests are included in gtk-config and will be added
|
||||
to GTK_LIBS and GTK_CFLAGS by the AM_PATH_GTK macro.
|
||||
|
||||
Owen Taylor
|
||||
14 Mar 1997
|
||||
Reference in New Issue
Block a user