Let's suppose you just finished writing
zardoz, a program to make
your head float from vortex to vortex. You've been using Autoconf to
provide a portability framework, but your `Makefile.in's have been
ad-hoc. You want to make them bulletproof, so you turn to Automake.
The first step is to update your `configure.in' to include the
automake needs. The way to do this is to add an
AM_INIT_AUTOMAKE call just after
Since your program doesn't have any complicating factors (e.g., it
gettext, it doesn't want to build a shared library),
you're done with this part. That was easy!
Now you must regenerate `configure'. But to do that, you'll need
autoconf how to find the new macro you've used. The
easiest way to do this is to use the
aclocal program to generate
your `aclocal.m4' for you. But wait... you already have an
`aclocal.m4', because you had to write some hairy macros for your
aclocal program lets you put your own macros into
`acinclude.m4', so simply rename and then run:
mv aclocal.m4 acinclude.m4 aclocal autoconf
Now it is time to write your `Makefile.am' for
zardoz is a user program, you want to install it where the
rest of the user programs go. Additionally,
zardoz has some
Texinfo documentation. Your `configure.in' script uses
AC_REPLACE_FUNCS, so you need to link against `@LIBOBJS@'.
So here's what you'd write:
bin_PROGRAMS = zardoz zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c zardoz_LDADD = @LIBOBJS@ info_TEXINFOS = zardoz.texi
Now you can run
automake --add-missing to generate your
`Makefile.in' and grab any auxiliary files you might need, and
GNU hello is renowned for its classic simplicity and versatility. This section shows how Automake could be used with the GNU Hello package. The examples below are from the latest beta version of GNU Hello, but with all of the maintainer-only code stripped out, as well as all copyright comments.
Of course, GNU Hello is somewhat more featureful than your traditional two-liner. GNU Hello is internationalized, does option processing, and has a manual and a test suite.
Here is the `configure.in' from GNU Hello:
dnl Process this file with autoconf to produce a configure script. AC_INIT(src/hello.c) AM_INIT_AUTOMAKE(hello, 1.3.11) AM_CONFIG_HEADER(config.h) dnl Set of available languages. ALL_LINGUAS="de fr es ko nl no pl pt sl sv" dnl Checks for programs. AC_PROG_CC AC_ISC_POSIX dnl Checks for libraries. dnl Checks for header files. AC_STDC_HEADERS AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h) dnl Checks for library functions. AC_FUNC_ALLOCA dnl Check for st_blksize in struct stat AC_ST_BLKSIZE dnl internationalization macros AM_GNU_GETTEXT AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \ src/Makefile tests/Makefile tests/hello], [chmod +x tests/hello])
The `AM_' macros are provided by Automake (or the Gettext library); the rest are standard Autoconf macros.
The top-level `Makefile.am':
EXTRA_DIST = BUGS ChangeLog.O SUBDIRS = doc intl po src tests
As you can see, all the work here is really done in subdirectories.
The `po' and `intl' directories are automatically generated
gettextize; they will not be discussed here.
In `doc/Makefile.am' we see:
info_TEXINFOS = hello.texi hello_TEXINFOS = gpl.texi
This is sufficient to build, install, and distribute the GNU Hello manual.
Here is `tests/Makefile.am':
TESTS = hello EXTRA_DIST = hello.in testdata
The script `hello' is generated by
configure, and is the
only test case.
make check will run this test.
Last we have `src/Makefile.am', where all the real work is done:
bin_PROGRAMS = hello hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h hello_LDADD = @INTLLIBS@ @ALLOCA@ localedir = $(datadir)/locale INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
Here is another, trickier example. It shows how to generate two
etags) from the same source file
(`etags.c'). The difficult part is that each compilation of
`etags.c' requires different
bin_PROGRAMS = etags ctags ctags_SOURCES = ctags_LDADD = ctags.o etags.o: etags.c $(COMPILE) -DETAGS_REGEXPS -c etags.c ctags.o: etags.c $(COMPILE) -DCTAGS -o ctags.o -c etags.c
ctags_SOURCES is defined to be empty--that way no
implicit value is substituted. The implicit value, however, is used to
etags from `etags.o'.
ctags_LDADD is used to get `ctags.o' into the link line.
ctags_DEPENDENCIES is generated by Automake.
The above rules won't work if your compiler doesn't accept both
`-c' and `-o'. The simplest fix for this is to introduce a
bogus dependency (to avoid problems with a parallel
etags.o: etags.c ctags.o $(COMPILE) -DETAGS_REGEXPS -c etags.c ctags.o: etags.c $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o
Also, these explicit rules do not work if the de-ANSI-fication feature is used (see section Automatic de-ANSI-fication). Supporting de-ANSI-fication requires a little more work:
etags._o: etags._c ctags.o $(COMPILE) -DETAGS_REGEXPS -c etags.c ctags._o: etags._c $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
As it turns out, there is also a much easier way to do this same task.
Some of the above techniques are useful enough that we've kept the
example in the manual. However if you were to build
ctags in real life, you would probably use per-program
compilation flags, like so:
bin_PROGRAMS = ctags etags ctags_SOURCES = etags.c ctags_CFLAGS = -DCTAGS etags_SOURCES = etags.c etags_CFLAGS = -DETAGS_REGEXPS
In this case Automake will cause `etags.c' to be compiled twice, with different flags. De-ANSI-fication will work automatically. In this instance, the names of the object files would be chosen by automake; they would be `ctags-etags.c' and `etags-etags.o'. (The name of the object files rarely matters.)