Pileus Git - ~andy/gtk/blob - docs/gtk-config.txt

   1 CONFIGURING PACKAGES TO WORK WITH GTK
   2 -------------------------------------
   3
   4 Compiling a program successfully against the GTK, GDK, and GLIB
   5 libraries can require a large number of command line options
   6 to your compiler and linker that are hard to guess correctly.
   7 The additional libraries required may, for example, depend on the
   8 manner which GTK was configured
   9
  10 Several tools are included in this package to make process
  11 easier.
  12
  13 First, there is the shell script 'gtk-config' (installed in
  14 $exec_prefix/bin):
  15
  16 Invoking gtk-config
  17 -------------------
  18
  19 gtk-config takes the following flags:
  20
  21   --version
  22      Prints out the version of GTK installed
  23
  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   --prefix[=PREFIX]
  31      If PREFIX is specified, overrides the configured value of $prefix.
  32      (And of exec-prefix, unless --exec-prefix is also specified)
  33      Otherwise, prints out the configured value of $prefix
  34
  35   --exec-prefix[=PREFIX]
  36      If PREFIX is specified, overrides the configured value of $exec_prefix.
  37      Otherwise, prints out the configured value of $exec_prefix
  38
  39 You may also add to the command line a list of additional
  40 libraries that gtk-config should supply the CFLAGS and LIBS
  41 for. The only currently supported library is 'gthread'.
  42
  43 As an example of this latter usage, you can get the
  44 appropriate cflags for a threaded program with:
  45
  46  gtk-config --cflags gthread
  47
  48
  49 Example of using gtk-config
  50 ---------------------------
  51
  52 Typically, gtk-config will be used within a configure script,
  53 as described below. It, however, can also be used directly
  54 from the command line to compile a simple program. For example:
  55
  56   cc -o simple `gtk-config --cflags` simple.c `gtk-config --libs`
  57
  58 This command line might expand to (for example):
  59
  60   cc -o simple -I/usr/local/lib/glib/include -I/usr/local/include \
  61     -I/usr/X11R6/include simple.c -L/usr/local/lib -L/usr/X11R6/lib \
  62     -lgtk -lgdk -lglib -lXi -lXext -lX11 -lm
  63
  64 Not only is the form using gtk-config easier to type, it will
  65 work on any system, no matter how GTK was configured.
  66
  67
  68 AM_PATH_GTK
  69 -----------
  70
  71 For packages configured using GNU automake, GTK also provides
  72 a macro to automate the process of running GTK.
  73
  74  AM_PATH_GTK([MINIMUM-VERSION, [ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]])
  75
  76 This macro:
  77
  78  * Determines the location of GTK using gtk-config, which is either
  79    found in the user's path, or from the environment variable
  80    GTK_CONFIG
  81
  82  * Tests the installed libraries to make sure that there version
  83    is later than MINIMUM-VERSION. (A default version will be used
  84    if not specified)
  85
  86  * If the required version was found, sets the GTK_CFLAGS variable to
  87    the output of `gtk-config --cflags` and the GTK_LIBS variable to
  88    the output of `gtk-config --libs`, and calls AC_SUBST() for these
  89    variables so they can be used in generated makefiles, and then
  90    executes ACTION-IF-FOUND.
  91
  92  * If the required version was not found, sets GTK_CFLAGS and GTK_LIBS
  93    to empty strings, and executes ACTION-IF-NOT-FOUND.
  94
  95 This macro is in file 'gtk.m4' which is installed in $datadir/aclocal.
  96 Note that if automake was installed with a different --prefix than
  97 GTK, you will either have to manually move gtk.m4 to automake's
  98 $datadir/aclocal, or give aclocal the -I option when running it.
  99
 100
 101 Configuring a package that uses AM_PATH_GTK
 102 -------------------------------------------
 103
 104 Simply make sure that gtk-config is in your path, and run
 105 the configure script.
 106
 107 Notes:
 108
 109 * The directory where the GTK libraries are installed needs
 110   to be found by your system's dynamic linker.
 111
 112   This is generally done by
 113
 114     editing /etc/ld.so.conf and running ldconfig
 115
 116   Or by:
 117
 118     setting the environment variable LD_LIBRARY_PATH,
 119
 120   or, as a last resort,
 121
 122     Giving a -R or -rpath flag (depending on your linker) when
 123     running configure, for instance:
 124
 125       LDFLAGS=-R/usr/home/owen/lib ./configure
 126
 127 * You can also specify a gtk-config not in your path by
 128   setting the GTK_CONFIG environment variable to the
 129   name of the executable
 130
 131 * If you move the GTK package from its installed location,
 132   you will need either need to modify gtk-config script
 133   manually to point to the new location or rebuild GTK.
 134
 135 Advanced note:
 136
 137 * configure flags
 138
 139   --with-gtk-prefix=PREFIX
 140   --with-gtk-exec-prefix=PREFIX
 141
 142   are provided to override the prefix and exec-prefix that were stored
 143   in the gtk-config shell script by GTK's configure. You are generally
 144   better off configuring GTK with the right path to begin with.
 145
 146 Example of a package using AM_PATH_GTK
 147 --------------------------------------
 148
 149 The following shows how to build a simple package using automake
 150 and the AM_PATH_GTK macro. The program used here is the testinput.c
 151
 152 You should first read the introductory portions of the automake
 153 Manual, if you are not already familiar with it.
 154
 155 Two files are needed, 'configure.ac', which is used to build the
 156 configure script:
 157
 158 ==configure.ac===
 159 dnl Process this file with autoconf to produce a configure script.
 160 AC_INIT(testinput.c)
 161
 162 AM_INIT_AUTOMAKE(testinput.c, 1.0.0)
 163
 164 AC_PROG_CC
 165 AM_PROG_CC_STDC
 166 AC_PROG_INSTALL
 167
 168 AM_PATH_GTK(0.99.5,
 169           [LIBS="$LIBS $GTK_LIBS"
 170            CFLAGS="$CFLAGS $GTK_CFLAGS"],
 171           AC_MSG_ERROR(Cannot find GTK: Is gtk-config in path?))
 172
 173 AC_OUTPUT(Makefile)
 174 =================
 175
 176 The only command in this which is not standard for automake
 177 is the AM_PATH_GTK() macro.
 178
 179 That command does the following:
 180
 181  If a GTK version greater than 0.99.5 is found, adds $GTK_LIBS to
 182  $LIBS and $GTK_CFLAGS to $CFLAGS. Otherwise, dies with the error
 183  message "Cannot find GTK: Is gtk-config in path?"
 184
 185 And the 'Makefile.am', which will be used to build the Makefile.
 186
 187 == Makefile.am ==
 188 bin_PROGRAMS = testinput
 189 testinput_SOURCES = testinput.c
 190 =================
 191
 192 This Makefile.am, says that we are building a single executable,
 193 from a single sourcefile 'testinput.c'. Since every program
 194 we are building uses GTK we simply added the GTK options
 195 to $LIBS and $CFLAGS, but in other circumstances, we might
 196 want to specify them on a per-program basis: for instance by
 197 adding the lines:
 198
 199   testinput_LDADD = $(GTK_LIBS)
 200   INCLUDES = $(GTK_CFLAGS)
 201
 202 to the Makefile.am.
 203
 204 To try this example out, create a new directory, add the two
 205 files above two it, and copy the testinput.c file from
 206 the gtk/ subdirectory to the new directory. Edit the line:
 207
 208   #include "gtk.h"
 209
 210 in testgtk.c, to read:
 211
 212   #include <gtk/gtk.h>
 213
 214
 215 Now execute the following commands:
 216
 217   automake --add-missing
 218   aclocal
 219   autoconf
 220
 221 You now have a package that can be built in the normal fashion
 222
 223   ./configure
 224   make
 225   make install
 226
 227
 228 Notes:
 229
 230 * If you are converting a package that used a pre-1.0 version of
 231   GTK, you should remove the autoconf tests for X. The results
 232   of these tests are included in gtk-config and will be added
 233   to GTK_LIBS and GTK_CFLAGS by the AM_PATH_GTK macro.
 234
 235                                         Owen Taylor
 236                                         14 Mar 1997