autoconf and automake are two utilities to make porting applications and setting them up for individual computers easier. However, getting started is a daunting task. It is not clear, since these are two separate packages, what needs to be done first, and how to create the configure.in and Makefile.am files.
If you have autoconf and automake installed on your system, you should be able to read the documentation using an info browser. The documentation is complete, but more for reference than instruction.
This document attempts to act as a tutorial for autoconf and automake for those who never used them before.
You will need the following packages: (if not already there, install them in this order)
Optional packages: gnu tar, texinfo, gnu make, gettext, and libtool. But I won't go there.
Note: if you don't use gnu tar, you may get a .tar.gz file which is in tar format, but not compressed. You will need to rename it to .tar and compress it by hand.
Since the intended audience should know how a Makefile is constructed, I will show the dependancies with a psuedo-makefile. It should be easy to determine which functions are run, when they need to be run, and what files they create. Those files in strong type are created by the developer. All other files are either derived, or supplied by automake and autoconf.
aclocal.m4 : configure.in acinclude.m4
aclocal
configure : configure.in aclocal.m4 $(optional)
autoconf
am_args = -i --foreign -a
Makefile.in : Makefile.am configure.in aclocal.m4
automake $(am_args)
#config.h.in is optional
optional=acconfig.h config.h.top config.h.bot
config.h.in : configure.in $(optional)
autoheader
config.status config.cache config.log config.h Makefile : \
Makefile.in
configure
The following are the minimal steps to create a configuration using autoconf/automake.
The following is similar to the above example, but it uses autoheader. After running aclocal:
A shallow configuration is one that has only one directory. Here is a sample.
Files:
After modifying configure.in, it should look like this:
A deep configuration has subdiretories, and possibly sudirectories of subdirectories. You get the idea. Here is a short example (with libraries).
Follow the steps above and you should get a configure.in like this:
That is about as simple as it gets.
Here are some useful variables you will need to use in your Makefile.am. To set the value of the variable, use name = value. Do not set variables marked with @@. This will be set at configuration time (./configure)
To use the value of a variable use $(name).
All variables are case-sensitive. Uppercase letters are not the same as lower case letters.
Note: all dashes and periods (and any other non-alphanumerics) must be changed to underscores.
More variables can be found in automake's info file under Generalities -> Uniform
Yes, it is nice to be able to enable and disable options at
configure time like ./configure --enable-threads, but it
will likely take about 2 hours of reading through the manuals to
figure out all the bits and pieces. Here is a quick look at
how to implement configuration options.
This example will demonstrate how to implement a simple(ton) --enable-threads configuration option. We will start with the "C" program's implementation. It will most likely have a conditional based on a "define" value, like so:
There is also a difference in the way the program is linked and compiled:
Without threads:
With threads:
To handle these differences, we will set LDADD and CFLAGS in Makefile.am, conditionally.
First, to make a #define from configure.in:
The AC_HELP_STRING will print out the option and description when
./configure --help is typed.
Next, put in a conditional for automake (still in configure.in)
Now, we have a conditional #define for the "C" program and a conditional for the Makefile.am. Next, we will modify Makefile.am to make use of the AM_CONDITIONAL
You can find some of the common portability issues from the autoconf info page under Existing Tests. This topic will give instructions on how to configure if you use particular programs, libraries, library functions, headers, structures, typedefs, compiler characteristics, system services, and UNIX variants.
autoscan will automatically find any programs, library functions, header files, structures, etc. which might need to be conditionally configured. It will place the autoconf macros in configure.scan. If you see a macro inserted by autoscan, you should check the documentation on the macro in the autoconf info page for more information on how to implement the configuration check.
The chicken and the egg is a creationist's problem. If God had made every living creature at the same time, did the chicken come first, who laid the egg, or did the egg come first which hatched into a chicken. Either way, one could not have existed unless the other had first existed.
In the case of autoscan and automake, it is almost a chicken and egg proposal. The main difference is that automake will not run without a configure.in, where autoscan will run without complaining without a Makefile.in. The only problem with running autoscan without a Makefile.in is that there are no files placed in AC_OUTPUT. That is why, on the initial configuration, the AC_OUTPUT(Makefile [ src/Makefile ...]) must be placed in the configure.in by hand.