autostuff.HOWTO

[John Kodis <kodis jagunet com>]

I've pulled together a description of how to use the aclocal and
auto{conf,header,make,scan} series of tools to generate a configure
file and a Makefile for a simple stand-alone Gnome application.

This is meant as a simple get-up-to-speed-quickly document in the
spirit of the GNOME Tricks and Tips series of articles.  It is not
complete or authoratative.  Rather, it's what I've been able to
uncover and apply by struggling with this stuff for a couple of days.

I'm quite a novice in this area, and would appreciate feedback and
corrections from those who are more experienced in this area.  In
particular, I haven't been able to figure out how to use the
GNOME_INIT or other test to define the GNOME_LIBS, GNOME_LIBDIR, and
other Gnome macros, and so have just left these hard-coded for now.
Similarly, defining PACKAGE and VERSION both individually and in
AM_INIT_AUTOMAKE seems less than optimal.

In any event, here's what I've got so far.

-- John Kodis.

--------

This is a quick and dirty guide to using the aclocal and
auto{conf,header,make,scan} series of programs to semiautomatically
create a configure script and a Makefile for a very simple stand-alone
Gnome application.

We'll start out with nothing but the source file that we're trying to
configure and build -- stripchart.c in this example.  Move into the
source directory, and run autoscan.  This will examine any source
files it finds (stripchart.c, in this case), and will generate
configure.scan based on its findings.

$ autoscan
$ ls
stripchart.c      configure.scan

Edit configure.scan into configure.in.  At a minimum, this involves
adding lines to generate Makefile.in from Makefile.am, to generate a
config.h file from config.h.in, and to find a C compiler to use.
These three lines go just after the initial AC_INIT line that autoscan
will put at the top of the file.

AC_INIT(stripchart.c)
AM_INIT_AUTOMAKE(stripchart, 1.4)
AM_CONFIG_HEADER(config.h)
AC_PROG_CC

The last line in configure.in should request that a Makefile be
generated:

AC_OUTPUT([Makefile])

Run aclocal to generate an aclocal.m4 file, then run autoconf to
generate a configure script from the configure.in file.

$ aclocal
$ autoconf
$ ls
aclocal.m4    chart.c       configure*    configure.in


Write a acconfig.h file containing the following two definitions for
PACKAGE and VERSION.  It seems like there should be an easy way to
pick this up from the AM_INIT_AUTOMAKE macro, but I haven't figured
out what it is yet.

#define PACKAGE "stripchart"
#define VERSION "1.4"

Run the autoheader program to generate config.h.in from the acconfig.h
file.  This file is used by the configure script to generate the
config.h file.  By #including this file, your program gains access to
macros describing the package name, version number, and the
availability of various system features and facilities.

$ autoheader
$ ls
acconfig.h     config.h.in    configure.in
aclocal.m4     stripchart.c   configure*


Write a Makefile.am file containing the following three assignments,
but with the proper program name substituted for "chart".  If other
source files are used, they should be included in the _SOURCES line if
autoscan doesn't pick them up for you.  Similarly, any additional
libraries get included in the _LDFLAGS line.

bin_PROGRAMS		= stripchart
stripchart_SOURCES	= stripchart.c
stripchart_LDFLAGS	= `gtk-config --libs` \
			  -ldl -lgdk_imlib -ltiff -ljpeg -lpng -lz \
			  -lSM -lICE -lgnomeui -lgnome -lgnomesupport


You should write proper NEWS, README, AUTHORS, and ChangeLog files
prior to distributing your work, but the build can proceed without
them, so for the time being just touch these files.  This will silence
a warning, and will give you several empty files to remind you what
remains to be done.

$ touch NEWS README AUTHORS ChangeLog

Run automake, specifying that it add a few standard files that can be
generated automatically.

$ automake --add-missing
$ ls
AUTHORS         Makefile.am     acconfig.h      configure*      mkinstalldirs@
COPYING@        Makefile.in     aclocal.m4      configure.in    stamp-h.in
ChangeLog       NEWS            chart.c         install-sh@
INSTALL@        README          config.h.in     missing@


At this point, you've got things set up just as they are after you've
just untarred a standard GNU software package.  All that's left to do
is the usual

./configure

This will generate a Makefile and a config.h file from the Makefile.in
and config.h.in files.  From here, it's just a matter of making the
package as usual.  The Makefile that automake generates will, on its
first invocation, compute the dependancies for the stripchart program,
then compile and link this into a working program.