gtk-config.txt 6.9 KB
Newer Older
1 2 3
CONFIGURING PACKAGES TO WORK WITH GTK
-------------------------------------

4
Compiling a program successfully against the GTK, GDK, and GLIB
5 6 7 8 9 10 11 12 13 14 15 16 17 18
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
-------------------

19
gtk-config takes the following flags:
20

21
  --version
22 23
     Prints out the version of GTK installed

24
  --cflags
25
     Prints '-I' flags pointing to the installed header files.
26

27
  --libs
28
     Prints out the linker flags necessary to link a program against GTK
29 30 31 32 33 34 35 36 37 38
   
  --prefix[=PREFIX]
     If PREFIX is specified, overrides the configured value of $prefix.
     (And of exec-prefix, unless --exec-prefix is also specified)
     Otherwise, prints out the configured value of $prefix

  --exec-prefix[=PREFIX]
     If PREFIX is specified, overrides the configured value of $exec_prefix.
     Otherwise, prints out the configured value of $exec_prefix
 
39 40 41 42 43 44 45 46
You may also add to the command line a list of additional
libraries that gtk-config should supply the CFLAGS and LIBS
for. The only currently supported library is 'gthread'.

As an example of this latter usage, you can get the
appropriate cflags for a threaded program with:

 gtk-config --cflags gthread
47

48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85

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)

86 87
 * If the required version was found, sets the GTK_CFLAGS variable to
   the output of `gtk-config --cflags` and the GTK_LIBS variable to
88 89 90 91
   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.

92
 * If the required version was not found, sets GTK_CFLAGS and GTK_LIBS
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
   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:

109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126
* The directory where the GTK libraries are installed needs
  to be found by your system's dynamic linker.
  
  This is generally done by

    editing /etc/ld.so.conf and running ldconfig

  Or by:
   
    setting the environment variable LD_LIBRARY_PATH, 

  or, as a last resort, 
 
    Giving a -R or -rpath flag (depending on your linker) when
    running configure, for instance:

      LDFLAGS=-R/usr/home/owen/lib ./configure

127 128 129 130 131 132 133 134
* 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.

135 136 137 138 139 140
Advanced note:

* configure flags
  
  --with-gtk-prefix=PREFIX
  --with-gtk-exec-prefix=PREFIX 
141

142 143 144
  are provided to override the prefix and exec-prefix that were stored
  in the gtk-config shell script by GTK's configure. You are generally
  better off configuring GTK with the right path to begin with.
145 146 147 148 149 150 151 152 153 154

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.

155
Two files are needed, 'configure.ac', which is used to build the
156 157
configure script:

158
==configure.ac===
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236
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