From 083b0e043240d212e19ac0d54bd5a3fbe72ecea4 Mon Sep 17 00:00:00 2001 From: Owen Taylor Date: Wed, 6 Mar 2002 23:36:37 +0000 Subject: [PATCH] Mention the need to subscribe to the GTK+ mailing lists. Wed Mar 6 18:11:05 2002 Owen Taylor * gtk/resources.sgml: Mention the need to subscribe to the GTK+ mailing lists. * gtk/building.sgml: Go into much more details about building the entire set of GTK+ libraries and about the dependencies that are required. * gtk/building.sgml: Add docs for --enable-explicit-deps, --with-xinput. --- docs/reference/ChangeLog | 12 + docs/reference/gtk/building.sgml | 383 ++++++++++++++++++++++++++---- docs/reference/gtk/resources.sgml | 3 + 3 files changed, 350 insertions(+), 48 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index c491983f07..4b2c0c9faa 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,15 @@ +Wed Mar 6 18:11:05 2002 Owen Taylor + + * gtk/resources.sgml: Mention the need to subscribe + to the GTK+ mailing lists. + + * gtk/building.sgml: Go into much more details about + building the entire set of GTK+ libraries and about the + dependencies that are required. + + * gtk/building.sgml: Add docs for --enable-explicit-deps, + --with-xinput. + Wed Mar 6 14:12:34 2002 Jonathan Blandford * gtk/tmpl/gtktreeselection.sgml: docs diff --git a/docs/reference/gtk/building.sgml b/docs/reference/gtk/building.sgml index 8cb24d6d49..de6aac2827 100644 --- a/docs/reference/gtk/building.sgml +++ b/docs/reference/gtk/building.sgml @@ -1,53 +1,301 @@ -Compiling the GTK+ package +Compiling the GTK+ libraries 3 GTK Library -Compiling the GTK+ Package +Compiling the GTK+ Libraries How to compile GTK+ itself - - - Building the Library on UNIX - - On UNIX, GTK+ uses the standard GNU build system, - using autoconf for package - configuration and resolving portability issues, - automake for building makefiles - that comply with the GNU Coding Standards, and - libtool for building shared - libraries on multiple platforms. The normal sequence for - compiling and installing the GTK+ library is thus: - - - ./configure - make - make install - - - - - The standard options provided by GNU - autoconf may be passed to the - configure script. Please see the - autoconf documentation or run - ./configure --help for information about - the standard options. - - - - + + Building GTK+ on UNIX-like systems + + This chapter covers building and installing GTK+ on UNIX and + UNIX-like systems such as Linux. Compiling GTK+ on Microsoft + Windows is different in detail and somewhat more difficult to + get going since the necessary tools aren't included with + the operating system. + + + Before we get into the details of how to compile GTK+, we should + mention that in many cases, binary packages of GTK+ prebuilt for + your operating system will be available, either from your + operating system vendor or from independent sources. If such a + set of packages is available, installing it will get you + programming wih GTK+ much faster than building it yourself. In + fact, you may well already have GTK+ installed on your system + already. + + + On UNIX-like systems GTK+ uses the standard GNU build system, + using autoconf for package + configuration and resolving portability issues, + automake for building makefiles that + comply with the GNU Coding Standards, and + libtool for building shared libraries + on multiple platforms. + + + If you are building GTK+ from the distributed source packages, + then won't need these tools installed; the necessary pieces + of the tools are already included in the source packages. But + it's useful to know a bit about how packages that use these + tools work. A source package is distributed as a + tar.gz file which you unpack into a + directory full of the source files as follows: + + + tar xvfz gtk+-2.0.0.tar.gz + + + In the toplevel of the directory that is created, there will be + a shell script called configure which + you then run to take the template makefiles called + Makefile.in in the package and create + makefiles customized for your operating system. The configure + script can be passed various command line arguments to determine how + the package is built and installed. The most commonly useful + argument is the --prefix argument which + determines where the package is installed. To install a package + in /opt/gtk you would run configure as: + + + ./configure --prefix=/opt/gtk + + + A full list of options can be found by running + configure with the + --help argument. In general, the defaults are + right and should be trusted. After you've run + configure, you then run the + make command to build the package and install + it. + + + make + make install + + + If you don't have permission to write to the directory you are + installing in, you may have to change to root temporarily before + running make install. + + + Several environment variables are useful to pass to set before + running configure. CPPFLAGS contains options to + pass to the C compiler, and is used to tell the compiler where + to look for include files. The LDFLAGS variable + is used in a similar fashion for the linker. Finally the + PKG_CONFIG_PATH environment variable contains + a search path that pkg-config (see below) + uses when looking for for file describing how to compile + programs using different libraries. If you were installing GTK+ + and it's dependencies into /opt/gtk, you might want to set + these variables as: + + + CPPFLAGS="-I /opt/gtk/include" + LDFLAGS="-L/opt/gtk/lib" + PKG_CONFIG_PATH="/opt/gtk/lib/pkgconfig" + export CPPFLAGS LDFLAGS PKG_CONFIG_PATH + + + You may also need to set the LD_LIBRARY_PATH + environment variable so the systems dynamic linker can find + the newly installed libraries, and the PATH + environment program so that utility binaries installed by + the various libraries will be found. + + + LD_LIBRARY_PATH="/opt/gtk/lib" + PATH="/opt/gtk/bin:$PATH" + export LD_LIBRARY_PATH PATH + + + + Dependencies + + Before you can compile the GTK+ widget toolkit, you need to have + various other tools and libraries installed on your + system. The two tools needed during the build process (as + differentiated from the tools used in when creating GTK+ + mentioned above such as autoconf) + are pkg-config and GNU make. + + + + + pkg-config + is a tool for tracking the compilation flags needed for + libraries that is used by the GTK+ libraries. (For each + library, a small ".pc" text file is installed in a standard + location that contains the compilation flags needed for that + library along with version number information.) The version + of pkg-config needed to build GTK+ is + mirrored in the dependencies directory + on the GTK+ FTP + site. + + + + + The GTK+ makefiles will mostly work with different versions + of make, however, there tends to be + a few incompatibilities, so the GTK+ team recommends + installing GNU + make if you don't already have it on your system + and using it. (It may be called gmake + rather than make) + + + + + Three of the libraries that GTK+ depends on are maintained by + by the GTK+ team: GLib, Pango, and ATK. Other libraries are + maintained separately. + + + + + The GLib library provides core non-graphical functionality + such as high level data types, unicode manipulation, and + a object and type system to C programs. It is available + from the GTK+ + FTP site. + + + + + Pango is a library for internationalized text handling. It + is available from the GTK+ FTP site. + + + + + ATK is the Accessibility Toolkit. It provides a set of generic + interfaces allowing accessibility technologies such as + screen readers to interact with a graphical user interface. + It is available from the GTK+ FTP site. + + + + + The GNU + libiconv library is needed to build GLib if your + system doesn't have the iconv() + function for doing conversion between character + encodings. Most modern systems should have + iconv(). + + + + + The libintl library from the GNU gettext + package is needed if your system doesn't have the + gettext() functionality for handling + message translation databases. + + + + + The JPEG, + PNG, and + TIFF image loading libraries are needed to + compile GTK+. You probably already have these libraries + installed, but if not, the versions you need are available in + the dependencies directory on the the + GTK+ + FTP site.. (Before installing these libraries + from source, you should check if your operating system + vendor has prebuilt packages of these libraries that you + don't have installed.) + + + + + While not required for running GTK+ on X, you may want install the + FreeType + library so that the PangoFT2 backend for Pango will + be built. This backend is used by the linux-fb backend for + GTK+ and applications that want to render independently + of the X display. You'll need at least version 2.0.1. + + + + + The libraries from the X window system are needed to build + Pango and GTK+. You should already have these installed on + your system, but it's possible that you'll need to install + the development environment for these libraries that your + operating system vendor provides. If you have a recent + version of the XFree86 system, such as 4.2.0, then Pango + and GTK+ will take advantage of the Xft and Xrender + libraries to provide anti-aliased and scaleable fonts in + a much more sophisticated fashion then the support for + core X fonts. + + + + + + Building and testing GTK+ + + First make sure that you have the necessary external + dependencies installed: pkg-config, GNU make, + the JPEG, PNG, and TIFF libraries, FreeType, and, if necessary, + libiconv and libintl. To get detailed information about building + ithese packages, see the documentation provided with the + individual packages. + On a Linux system, it's quite likely you'll have all of these + installed already except for pkg-config. + + + Then build and install the GTK+ libraries in the order: + GLib, Pango, ATK, then GTK+. For each library, follow the + steps of configure, make, + make install mentioned above. If you're + lucky, this will all go smoothly, and you'll be ready to + start compiling your own GTK+ + applications. You can test your GTK+ installation + by running the gtk-demo program that + GTK+ installs. If you have the Xft library, you can turn on + anti-aliased fonts by setting the GDK_USE_XFT + environment variable. + + + GDK_USE_XFT=1 gtk-demo + + + If one of the configure scripts fails or running + make fails, look closely at the at the error + messages printed; these will often provide useful information + as to what went wrong. When configure + fails, extra information, such as errors that a test compilation + ran into, is found in the file config.log. + Looking at the last couple of hundred lines in this file will + frequently make clear what went wrong. If all else fails, you + can ask for help on the gtk-list mailing list. + See for more information. + + + Extra Configuration Options In addition to the normal options, the - configure script in the GTK+ - library supports these additional arguments: + configure script for the GTK+ library + supports a number of additional arguments. (Command line + arguments for the other GTK+ libraries are described in + the documentation distributed with the those libraries.) configure @@ -141,6 +389,31 @@ How to compile GTK+ itself + + <systemitem>--enable-explicit-deps</systemitem> and + <systemitem>--disable-explicit-deps</systemitem> + + If --enable-explicit-deps is + specified then GTK+ will write the full set of libraries + that GTK+ depends upon into its .pc files to be used when + programs depending on GTK+ are linked. Otherwise, GTK+ + only will include the GTK+ libraries themselves, and + will depend on system library dependency facilities to + bring in the other libraries. + By default GTK+ will disable explicit dependencies unless + it detects that they are needed on the system. (If you + specify --enable-static to force + building of static libraries, then explicit dependencies + will be written since library dependencies don't work + for static libraries.) Specifying + --enable-explicit-deps or + --enable-static can cause + compatibility + problems when libraries that GTK+ depends upon change + their versions, and should be avoided if possible. + + + <systemitem>--disable-shm</systemitem> and <systemitem>--enable-shm</systemitem> @@ -194,27 +467,37 @@ How to compile GTK+ itself --enable-gtk-doc - By default the configure script will try - to auto-detect whether the - gtk-doc package is installed. If - it is, then it will use it to extract and build the - documentation for the GTK+ library. These options - can be used to explicitly control whether - gtk-doc should be - used or not. If it is not used, the distributed, - pre-generated HTML files will be installed instead of - building them on your machine. + The gtk-doc package is + used to generate the reference documented included + with GTK+. By default support for gtk-doc is disabled + because it requires various extra dependencies + to be installed. If you have + gtk-doc installed and + are modifying GTK+, you may want to enable + gtk-doc support by passing + in --enable-gtk-doc. If not + enabled pre-generated HTML files distributed with GTK+ + will be installed. <systemitem>--with-xinput</systemitem> - - + Controls whether GTK+ is built with support for the XInput + extension. The XInput extension provides an interface + to extended input devices such as graphics tablets. + When this support is compiled in, specially written + GTK+ programs can get access to subpixel positions, + multiple simultaneous input devices, and extra "axes" + provided by the device such as pressure and tilt + information. This is only known to work well on XFree86 + systems, though other systems do have this extension. + (If --with-xinput=gxi + is supplied, support for an obsolete and unsupported + way of interacting with XInput is compiled.) - <systemitem>--with-gdktarget</systemitem> @@ -238,3 +521,7 @@ How to compile GTK+ itself + + + + diff --git a/docs/reference/gtk/resources.sgml b/docs/reference/gtk/resources.sgml index 6982c0ee38..1ad55d0c02 100644 --- a/docs/reference/gtk/resources.sgml +++ b/docs/reference/gtk/resources.sgml @@ -69,6 +69,9 @@ libraries. Discussion of GLib, Pango, and ATK in addition to GTK+ proper is welcome on these lists. You can subscribe or view the archives of these lists on http://mail.gnome.org. +If you aren't subscribed to the list, any message you post to +the list will be held for manual moderation, which might take +some days to happen.