1 CONFIGURING PACKAGES TO WORK WITH GTK
2 -------------------------------------
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
10 Several tools are included in this package to make process
13 First, there is the shell script 'gtk-config' (installed in
19 gtk-config takes the following flags:
22 Prints out the version of GTK installed
25 Prints '-I' flags pointing to the installed header files.
28 Prints out the linker flags necessary to link a program against GTK
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
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
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'.
43 As an example of this latter usage, you can get the
44 appropriate cflags for a threaded program with:
46 gtk-config --cflags gthread
49 Example of using gtk-config
50 ---------------------------
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:
56 cc -o simple `gtk-config --cflags` simple.c `gtk-config --libs`
58 This command line might expand to (for example):
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
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.
71 For packages configured using GNU automake, GTK also provides
72 a macro to automate the process of running GTK.
74 AM_PATH_GTK([MINIMUM-VERSION, [ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]])
78 * Determines the location of GTK using gtk-config, which is either
79 found in the user's path, or from the environment variable
82 * Tests the installed libraries to make sure that there version
83 is later than MINIMUM-VERSION. (A default version will be used
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.
92 * If the required version was not found, sets GTK_CFLAGS and GTK_LIBS
93 to empty strings, and executes ACTION-IF-NOT-FOUND.
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.
101 Configuring a package that uses AM_PATH_GTK
102 -------------------------------------------
104 Simply make sure that gtk-config is in your path, and run
105 the configure script.
109 * The directory where the GTK libraries are installed needs
110 to be found by your system's dynamic linker.
112 This is generally done by
114 editing /etc/ld.so.conf and running ldconfig
118 setting the environment variable LD_LIBRARY_PATH,
120 or, as a last resort,
122 Giving a -R or -rpath flag (depending on your linker) when
123 running configure, for instance:
125 LDFLAGS=-R/usr/home/owen/lib ./configure
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
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.
139 --with-gtk-prefix=PREFIX
140 --with-gtk-exec-prefix=PREFIX
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.
146 Example of a package using AM_PATH_GTK
147 --------------------------------------
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
152 You should first read the introductory portions of the automake
153 Manual, if you are not already familiar with it.
155 Two files are needed, 'configure.in', which is used to build the
159 dnl Process this file with autoconf to produce a configure script.
162 AM_INIT_AUTOMAKE(testinput.c, 1.0.0)
169 [LIBS="$LIBS $GTK_LIBS"
170 CFLAGS="$CFLAGS $GTK_CFLAGS"],
171 AC_MSG_ERROR(Cannot find GTK: Is gtk-config in path?))
176 The only command in this which is not standard for automake
177 is the AM_PATH_GTK() macro.
179 That command does the following:
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?"
185 And the 'Makefile.am', which will be used to build the Makefile.
188 bin_PROGRAMS = testinput
189 testinput_SOURCES = testinput.c
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
199 testinput_LDADD = $(GTK_LIBS)
200 INCLUDES = $(GTK_CFLAGS)
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:
210 in testgtk.c, to read:
215 Now execute the following commands:
217 automake --add-missing
221 You now have a package that can be built in the normal fashion
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.