GTK+ / Gnome Application Development
<<< Previous	Home	Next >>>

Creating Your Source Tree

Table of Contents
Overview of a Gnome Source Tree
Source Tree Checklist
configure.in
Makefile.am
Relevant GNU Documentation
Installing Support Files

Almost all Gnome applications use the same build system based on the GNU tools automake, autoconf, and libtool. GTK+ and Gnome provide a set of autoconf macros that make it easy to create a portable, standards-compliant build setup. Due to the bewildering array of tools involved, it can be difficult to figure out how Gnome source trees work; there are manuals available for each tool, but none describes the "big picture." This chapter gives you a simple overview that should help you get started. It also covers some Gnome-specific details, and tells you how to ship and install your application's icons, translations, and documentation.

If you're writing a large application, or a library, this chapter won't have all the information you need; you will probably need to consult the GNU tools' manuals to get more details. A complete discussion would fill the entire book.

Beginning with this chapter and continuing throughout Part 2 of the book, a sample application called GnomeHello will be used to demonstrate Gnome features. The GnomeHello source code is listed in Appendix E and the entire GnomeHello source tree is available online. It may be convenient to use it as a template for your own application's source code.

You may miss the simple Makefile made possible by the gtk-config script; there is an equivalent gnome-config script (use gnome-config --help to learn how to use it). However, these simple makefiles are not adequate for any real-world application.

Overview of a Gnome Source Tree

Gnome application build trees and distributed tarballs follow a set of conventions, most of them widespread in the free software community. Aspects of these conventions are formalized in documents such as the GNU Project's Coding Standards (http://www.gnu.org/prep/standards_toc.html) and the Linux Filesystem Hierarchy Standard (http://www.pathname.com/fhs/). It's worth using these standards even with non-free software---partially because they are very good from a technical standpoint, and partially because "going with the flow" will save you a lot of trouble, especially if you're using the GNU toolset. Besides, you might want to free your software someday.

The GNU toolset, including automake and autoconf will make it easy to comply with these standards. However, sometimes there are reasons not to use the GNU tools; for example, you may want a unified build that works on platforms such as Windows and MacOS. (Some of the tools do work with Windows using the Cygnus "Cygwin" environment, however; see http://sourceware.cygnus.com/cygwin.)

If you use autoconf and automake, users are not required to have these tools in order to build your software. The purpose of the tools is to build portable shell scripts and makefiles that will work in the user's environment.

The autoconf package encompasses the aclocal, autoheader, and autoconf executables. Together, these tools are used to create a portable shell script called configure; configure is distributed to users with your software package. It explores the compilation system and creates makefiles and a special header called config.h. The files created by configure are adapted to the specifics of the user's system.

configure creates each Makefile from a template, called Makefile.in; automake is a tool for creating these templates. automake generates Makefile.in from a hand-written Makefile.am. You distribute Makefile.in with your software, and users create a Makefile when they run configure.

The libtool package is the third important GNU tool; its purpose is to abstract the idiosyncracies of shared libraries (static library behavior is fairly uniform across UNIX-like systems, but shared libraries present major portability issues).

Informally, here are some of characteristics most Gnome packages have in common:

A file called README that describes the package.
A file called INSTALL that explains how to compile and install the package.
A script called configure that automatically adapts the program to platform-specific features (or the lack thereof). configure is expected to take an argument --prefix, specifying where to install the package.
Standard make targets, such as clean, etc.
A file called COPYING containing the package's copyright.
A ChangeLog in which changes to the software are recorded.
Tar files are traditionally compressed with gzip and their name includes the package version (for example, foo-0.2.1.tar.gz). They should unpack into a single directory, named with package and version---foo-0.2.1.
Internationalization is provided via the GNU gettext package. A copy of gettext is shipped along with the application, so users do not have to have one.