Glimmer: Tools: Autoconf and Automake
From CSWiki
Contents |
Summary
Autoconf and Automake are tools that make it easier for you to write software that is comparatively easy for others to build and install on other systems (primarily other Unix systems, including Linux and OS X, but sometimes even on Microsoft Windows systems). In Glimmer labs, we try to use Autoconf and Automake for our major projects, including MediaScript.
There are two primary ways in which one interacts with Autoconf and Automake. Clients use them to build systems from source. (You've probably done this by now.) Developers use them to build the scripts that clients use.
Background
When you learned C programming on Linux/Unix, you should have learned about Makefiles. Ideally, Makefiles provide a convenient way for both you and the people to whom you distribute software to easily build, customize, and install software.
When I learned about Make (oh, say, in the mid 1980's), in order to compile a piece of software for a new system, one would have to edit the Makefile by hand. ("Hmmm ... where do we keep these libraries on our machine? What about the Fortran compiler? Does my C compiler support calloc?") And, believe it or not, not, not everyone who wanted to install software knew how to edit Makefiles. There was also a lack of consistency in the kinds of targets packages had. (E.g., some folks would include an install or a clean target, others would not.)
In response, some folks in the free software community (I believe folks associated with FSF, but I'm too lazy to look it up) came up with Autoconf and Automake. Autoconf handles the messy configuration details: It helps find compilers and libraries and provides appropriate substitutes (or at least compile flags) if some libraries or procedures are unavailable. Automake handles the construction of Makefiles. You provide Automake with a summary of the parts of your project, and it creates a Makefile with both configuration options from Autoconf and with a huge collection of useful targets.
Using Autoconf and Automake as a client
Since the primary goal of Autoconf and Automake is to make it easier for clients to install software, the typical use of Autoconf and Automake is fairly straightforward. You configure the code for your system with ./configure, build it with make and install with make install.
However, to be a successful client of Autoconf and Automake, you should understand a few more things.
Running Configure Scripts
As the prior suggests, the most straightforward use of configure scripts is just to run the script.
./configure
However, one often wants to actually configure how the configure script should run. The most common configuration option is where to install the software. One uses the --prefix flag to tell Configure where to install the software (actually, the parent directory of where to install the software). For example, it seems that the typical install location is /usr/local (so executables go in /usr/local/bin, headers in /usr/local/include, libraries in /usr/local/lib, etc.). When installing from source on our Ubuntu boxes, it may be useful to overwrite the default install, which is rooted at /usr
./configure --prefix=/usr
Similarly, we tend to put Glimmer code in /glimmer on MathLAN machines. (Talk to Sam about how he gets it from one machine to all of the rest.)
./configure --prefix=/glimmer
You can also change/extend some of the standard environment variables when configuring. In this case, you write VARIABLE=value. For example, when building MediaScript, I like to turn debug flags on and to get warnings about possible violations in my code.
./configure CFLAGS="-g -Wall"
A number of packages have package-specific configurations. For example, MediaScript lets you disable Python, disable Scheme, and disable building the GIMP plugin. Since there are problems with the Python extension, we tend to disable Python. The disable options usually have the form --disable-thing.
./configure --disable-python
Putting it all together, here is a typical configure command for MediaScript.
./configure --disable-python --prefix=/glimmer CFLAGS="-g -Wall"
You can find out what options are available using
./configure --help
Building, Installing, and Beyond
We use make (and the corresponding Makefiles) to build and install software. The easiest command is
make
This command builds the software, or at least the parts of the software that the designers thought were most useful for you. Typically, the software is then left in the local directory. For others to use it naturally, you need to install the software, moving it to some standard location (/usr/bin or /usr/local/bin for executables, /usr/include or /usr/local/include for headers, etc.).
Of course, before installing software, you should test to make sure that it works correctly. Many packages include a check target.
make check
If the tests succeed (or, perhaps, if enough tests succeed that you're willing to install imperfect software), you can actually install the softare. You do so by giving make a target of install
make install
As you've probably noted, building software ends up in the creation of a lot of temporary files (.o files from .c files, maybe some library files, who knows what else). If you don't expect to rebuild the software frequently, it's a good idea to clean up all of these temporary files. In addition, after making a lot of changes to the system, it is also sometimes safer to clean out these files and rebuild from scratch. In both cases, you clean out the files with
make clean
A Few More Targets for Designers
For large software projects, it is also helpful to have a dist target that packages up all of the source code into a tar file. Of course, you also want to make sure that everything necessary got put in that tar file. You do so with the distcheck target.
Using Autoconf and Automake as a developer
Using Autoconf
Typically, you write a description of the features you require in a configure.ac file, and Autoconf produces a shell script called configure, which you then distribute with your code.
When someone runs configure, it looks through the system and determines the availability and location of various things. (It can also refuse to configure stuff if it can't find those files.) So, what do you do as a designer?
- Decide which programs, libraries, and such are necessary for your package.
- Decide which parts of your package are optional.
- Decide which files in your package need to be updated depending on the client's settings of the two prior variables. (All the Makefiles will be; others may be, too.)
- Write a
configure.acfile to embody those decisions. - Run
autoconf(or, more frequently,autoreconf) to buildconfigurefromconfigure.ac
Getting Started with Autoscan
Generating configure.ac with no prior experience can be a daunting task. To help build configure.ac, there is a cool tool called autoscan that looks at your project and figures out the basics.
- Type
autoscanin your top-level directory. - Read ane make notes about the warnings it gives you.
- Copy
configure.scantoconfigure.ac - Edit your brand new
configure.ac(it should be obvious what you need to do). - Cross your fingers.
Important parts of configure.ac
-
AC_PREREQ(2.61) - Indicates which version of Autoconf we're relying on. (Newer versions of Autoconf can add or remove features, change syntax, etc.)
-
AC_INIT([MediaScript], [0.0.1.14], [rebelsky@grinnell.edu]) - Gives the package name, the version number (I put a suffix of 'd' on versions during development, and person to contact with bugs. The square brackets indicate strings (whee!).
-
AM_INIT_AUTOMAKE - Tells Autoconf that it also has to set up Automake.
-
AC_PROG_RANLIBandAC_PRO_CC - Tells Autoconf that you'll be using ranlib and cc, that it has to find them, and that it should set up some variables to indicate where they are to be found.
-
AC_CHECK_LIB([libname], [procname]) - Checks whether the library is installed and has a procedure with the given name. If so, it defines a global variable (HAVE_LIBname) and adds the library to the list of things that are linked during compilation.
-
AC_CHECK_LIB([libname], [procname], [], [echo "message"; exit 1]) - A more sophisticated check that gives up if the library is not installed.
-
AC_CHECK_HEADERS([stdlib.h strings.h]) - Checks to make sure that headers are installed. If they are, some global variables get set. (I'm not sure that we use these checks correctly in the code.)
-
AC_CONFIG_FILES([Makefile src/Makefile ...]) - Builds these files from files with the same name and a suffix of
.in, primarily by substituting the computed variables (which are represented as@variable@in the .in file.
More to come later.
Using Automake
Putting it All Together
References
- Autotools: A Guide to Autoconf, Automake, and Libtool is one of Sam's favorite references on Autoconf and Automake, although it is a bit long.
- Using GNU Autotools (PDF) is a very long powerpoint-style presentation on the Autotools that Sam found useful when he was learning the tools
- The primary site for Automake has a long reference manual, which is useful when you need to look something up.
- The primary site for Autoconf also has a long reference manual, which serves the same purposes.
| Glimmer | Agendas | Links | References | Tasks |
