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

   1 CONFIGURING PACKAGES TO WORK WITH GTK
   2 -------------------------------------
   3
   4 Compiling a program succesfully 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 can be invoked in one of three forms:
  20
  21   gtk-config --version
  22      Prints out the version of GTK installed
  23
  24   gtk-config --cflags
  25      Prints '-I' flags pointing to the installed d
  26
  27   gtk-config --libs
  28      Prints out the linker flags necessary to link a program against GTK
  29
  30
  31 Example of using gtk-config
  32 ---------------------------
  33
  34 Typically, gtk-config will be used within a configure script,
  35 as described below. It, however, can also be used directly
  36 from the command line to compile a simple program. For example:
  37
  38   cc -o simple `gtk-config --cflags` simple.c `gtk-config --libs`
  39
  40 This command line might expand to (for example):
  41
  42   cc -o simple -I/usr/local/lib/glib/include -I/usr/local/include \
  43     -I/usr/X11R6/include simple.c -L/usr/local/lib -L/usr/X11R6/lib \
  44     -lgtk -lgdk -lglib -lXi -lXext -lX11 -lm
  45
  46 Not only is the form using gtk-config easier to type, it will
  47 work on any system, no matter how GTK was configured.
  48
  49
  50 AM_PATH_GTK
  51 -----------
  52
  53 For packages configured using GNU automake, GTK also provides
  54 a macro to automate the process of running GTK.
  55
  56  AM_PATH_GTK([MINIMUM-VERSION, [ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]])
  57
  58 This macro:
  59
  60  * Determines the location of GTK using gtk-config, which is either
  61    found in the user's path, or from the environment variable
  62    GTK_CONFIG
  63
  64  * Tests the installed libraries to make sure that there version
  65    is later than MINIMUM-VERSION. (A default version will be used
  66    if not specified)
  67
  68  * If the required version was found, sets the GTK_CFLAGS variable to
  69    the output of `gtk-config --cflags` and the GTK_LIBS variable to
  70    the output of `gtk-config --libs`, and calls AC_SUBST() for these
  71    variables so they can be used in generated makefiles, and then
  72    executes ACTION-IF-FOUND.
  73
  74  * If the required version was not found, sets GTK_CFLAGS and GTK_LIBS
  75    to empty strings, and executes ACTION-IF-NOT-FOUND.
  76
  77 This macro is in file 'gtk.m4' which is installed in $datadir/aclocal.
  78 Note that if automake was installed with a different --prefix than
  79 GTK, you will either have to manually move gtk.m4 to automake's
  80 $datadir/aclocal, or give aclocal the -I option when running it.
  81
  82
  83 Configuring a package that uses AM_PATH_GTK
  84 -------------------------------------------
  85
  86 Simply make sure that gtk-config is in your path, and run
  87 the configure script.
  88
  89 Notes:
  90
  91 * You can also specify a gtk-config not in your path by
  92   setting the GTK_CONFIG environment variable to the
  93   name of the executable
  94
  95 * If you move the GTK package from its installed location,
  96   you will need either need to modify gtk-config script
  97   manually to point to the new location or rebuild GTK.
  98
  99   [ As a future enhancement AM_PATH_GTK should support options
 100     to override the default locations found in gtk-config ]
 101
 102
 103 Example of a package using AM_PATH_GTK
 104 --------------------------------------
 105
 106 The following shows how to build a simple package using automake
 107 and the AM_PATH_GTK macro. The program used here is the testinput.c
 108
 109 You should first read the introductory portions of the automake
 110 Manual, if you are not already familiar with it.
 111
 112 Two files are needed, 'configure.in', which is used to build the
 113 configure script:
 114
 115 ==configure.in===
 116 dnl Process this file with autoconf to produce a configure script.
 117 AC_INIT(testinput.c)
 118
 119 AM_INIT_AUTOMAKE(testinput.c, 1.0.0)
 120
 121 AC_PROG_CC
 122 AM_PROG_CC_STDC
 123 AC_PROG_INSTALL
 124
 125 AM_PATH_GTK(0.99.5,
 126           [LIBS="$LIBS $GTK_LIBS"
 127            CFLAGS="$CFLAGS $GTK_CFLAGS"],
 128           AC_MSG_ERROR(Cannot find GTK: Is gtk-config in path?))
 129
 130 AC_OUTPUT(Makefile)
 131 =================
 132
 133 The only command in this which is not standard for automake
 134 is the AM_PATH_GTK() macro.
 135
 136 That command does the following:
 137
 138  If a GTK version greater than 0.99.5 is found, adds $GTK_LIBS to
 139  $LIBS and $GTK_CFLAGS to $CFLAGS. Otherwise, dies with the error
 140  message "Cannot find GTK: Is gtk-config in path?"
 141
 142 And the 'Makefile.am', which will be used to build the Makefile.
 143
 144 == Makefile.am ==
 145 bin_PROGRAMS = testinput
 146 testinput_SOURCES = testinput.c
 147 =================
 148
 149 This Makefile.am, says that we are building a single executable,
 150 from a single sourcefile 'testinput.c'. Since every program
 151 we are building uses GTK we simply added the GTK options
 152 to $LIBS and $CFLAGS, but in other circumstances, we might
 153 want to specify them on a per-program basis: for instance by
 154 adding the lines:
 155
 156   testinput_LDADD = $(GTK_LIBS)
 157   INCLUDES = $(GTK_CFLAGS)
 158
 159 to the Makefile.am.
 160
 161 To try this example out, create a new directory, add the two
 162 files above two it, and copy the testinput.c file from
 163 the gtk/ subdirectory to the new directory. Edit the line:
 164
 165   #include "gtk.h"
 166
 167 in testgtk.c, to read:
 168
 169   #include <gtk/gtk.h>
 170
 171
 172 Now execute the following commands:
 173
 174   automake --add-missing
 175   aclocal
 176   autoconf
 177
 178 You now have a package that can be built in the normal fashion
 179
 180   ./configure
 181   make
 182   make install
 183
 184
 185 Notes:
 186
 187 * If you are converting a package that used a pre-1.0 version of
 188   GTK, you should remove the autoconf tests for X. The results
 189   of these tests are included in gtk-config and will be added
 190   to GTK_LIBS and GTK_CFLAGS by the AM_PATH_GTK macro.
 191
 192                                         Owen Taylor
 193                                         14 Mar 1997