summaryrefslogtreecommitdiff
path: root/docs/gtk-config.txt
diff options
context:
space:
mode:
authorOwen Taylor <otaylor@src.gnome.org>1998-03-14 09:52:03 +0000
committerOwen Taylor <otaylor@src.gnome.org>1998-03-14 09:52:03 +0000
commitab4fed04fe6da912c7bf10449157dc5d3a93e448 (patch)
tree4de20ae3359919119320f0a2c6447075f27f9b3b /docs/gtk-config.txt
parentc86bf9bae2e939c84254dc2b7308f56948f18df4 (diff)
downloadgdk-pixbuf-ab4fed04fe6da912c7bf10449157dc5d3a93e448.tar.gz
Documentation about gtk-config and AM_PATH_GTK
Diffstat (limited to 'docs/gtk-config.txt')
-rw-r--r--docs/gtk-config.txt193
1 files changed, 193 insertions, 0 deletions
diff --git a/docs/gtk-config.txt b/docs/gtk-config.txt
new file mode 100644
index 000000000..5e3b6da67
--- /dev/null
+++ b/docs/gtk-config.txt
@@ -0,0 +1,193 @@
+CONFIGURING PACKAGES TO WORK WITH GTK
+-------------------------------------
+
+Compiling a program succesfully against the GTK, GDK, and GLIB
+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
+-------------------
+
+gtk-config can be invoked in one of three forms:
+
+ gtk-config --version
+ Prints out the version of GTK installed
+
+ gtk-config --cflags
+ Prints '-I' flags pointing to the installed d
+
+ gtk-config --libs
+ Prints out the linker flags necessary to link a program against GTK
+
+
+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)
+
+ * If the required version was found, sets the GDK_CFLAGS variable to
+ the output of `gtk-config --cflags` and the GDK_LIBS variable to
+ 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.
+
+ * If the required version was not found, sets GDK_CFLAGS and GDK_LIBS
+ 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:
+
+* 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.
+
+ [ As a future enhancement AM_PATH_GTK should support options
+ to override the default locations found in gtk-config ]
+
+
+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.
+
+Two files are needed, 'configure.in', which is used to build the
+configure script:
+
+==configure.in===
+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