Source Tree Checklist

As an initial overview, here are the important steps in creating a skeletal Gnome source tree. If you are starting a new program, you can simply follow this list and you won't forget anything. The rest of this chapter explains the checklist in more detail. It might also be helpful to download a Gnome package or two to look at as you follow the discussion (in particular, the "GnomeHello" source tree is intended to illustrate a proper build setup).

1. Create a toplevel directory to hold all the components of your application, including build files, documentation, and translations.

2. It's often nice to create a src subdirectory of this toplevel directory to keep source code separate from everything else.

3. In the toplevel directory, create AUTHORS, NEWS, COPYING, and README files. If desired, also create an empty ChangeLog.

4. Write a configure.in; the main purpose of configure.in is to determine which compiler, compiler flags, and linker flags to use. configure.in can also #define symbols to reflect features of the current platform, placing these definitions in the automatically-generated file config.h.

5. Write acconfig.h, which is a template for config.h.in. This file should #undef each symbol you will potentially #define in config.h. The autoheader program creates config.h.in based on acconfig.h, and autoconf creates config.h. autoheader comes with autoconf.

6. Create an empty file, stamp.h.in; this is used by the AM_CONFIG_HEADER macro in configure.in.

7. Write a Makefile.am in the toplevel directory listing each subdirectory which contains source code; in each subdirectory, also write a Makefile.am.

8. Run the gettextize program that comes with the gettext package. This creates the intl and po directories, needed for internationalization (gettextize is documented in the gettext manual). The intl contains the GNU gettext source code; if users compiling the program do not have gettext, they can pass the --with-included-gettext option to configure to automatically compile a static version in the intl directory. The po directory holds the translation files; gettextize will also create a file called po/Makefile.in.in, used to build the translations.

9. Create a file called po/POTFILES.in listing source files which should be scanned for strings to translate. POTFILES.in can be empty at first.

10. Copy autogen.sh and the macros directory from another Gnome module. You must modify autogen.sh to reflect the name of your package. Running autogen.sh will invoke libtoolize, aclocal, autoheader, automake, and autoconf.

11. autogen.sh invokes automake with the --add-missing argument. This will add some files, such as INSTALL with generic installation instructions. You can (and should) edit INSTALL to include any specific instructions for your application. autogen.sh will also create a Makefile in each directory.