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