4. Some example packages

This section contains two small examples.

The first example (see section A simple example, start to finish) assumes you have an existing project already using Autoconf, with handcrafted `Makefile's, and that you want to convert it to using Automake. If you are discovering both tools, it is probably better that you look at the Hello World example presented earlier (see section A Small Hello World).

The second example (see section Building true and false) shows how two programs can be built from the same file, using different compilation parameters. It contains some technical digressions that are probably best skipped on first read.

4.1 A simple example, start to finish

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.ac' to include the commands that automake needs. The way to do this is to add an AM_INIT_AUTOMAKE call just after AC_INIT:

AC_INIT([zardoz], [1.0])
AM_INIT_AUTOMAKE
…

Since your program doesn't have any complicating factors (e.g., it doesn't use 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 to tell 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… maybe you already have an `aclocal.m4', because you had to write some hairy macros for your program. The 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. Since zardoz is a user program, you want to install it where the rest of the user programs go: bindir. Additionally, zardoz has some Texinfo documentation. Your `configure.ac' 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 you're done!

4.2 Building true and false

Here is another, trickier example. It shows how to generate two programs (true and false) from the same source file (`true.c'). The difficult part is that each compilation of `true.c' requires different cpp flags.

bin_PROGRAMS = true false
false_SOURCES =
false_LDADD = false.o

true.o: true.c
        $(COMPILE) -DEXIT_CODE=0 -c true.c

false.o: true.c
        $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c

Note that there is no true_SOURCES definition. Automake will implicitly assume that there is a source file named `true.c' (see section Default _SOURCES), and define rules to compile `true.o' and link `true'. The `true.o: true.c' rule supplied by the above `Makefile.am', will override the Automake generated rule to build `true.o'.

false_SOURCES is defined to be empty--that way no implicit value is substituted. Because we have not listed the source of `false', we have to tell Automake how to link the program. This is the purpose of the false_LDADD line. A false_DEPENDENCIES variable, holding the dependencies of the `false' target will be automatically generated by Automake from the content of false_LDADD.

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 make):

true.o: true.c false.o
        $(COMPILE) -DEXIT_CODE=0 -c true.c

false.o: true.c
        $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o

Also, these explicit rules do not work if the obsolete de-ANSI-fication feature is used (see section Automatic de-ANSI-fication). Supporting de-ANSI-fication requires a little more work:

true_.o: true_.c false_.o
        $(COMPILE) -DEXIT_CODE=0 -c true_.c

false_.o: true_.c
        $(COMPILE) -DEXIT_CODE=1 -c true_.c && mv true_.o false_.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 true and false in real life, you would probably use per-program compilation flags, like so:

bin_PROGRAMS = false true

false_SOURCES = true.c
false_CPPFLAGS = -DEXIT_CODE=1

true_SOURCES = true.c
true_CPPFLAGS = -DEXIT_CODE=0

In this case Automake will cause `true.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 `false-true.o' and `true-true.o'. (The name of the object files rarely matters.)

This document was generated on July, 20 2009 using texi2html 1.76.