Autotools Tutorial

This is the home of my tutorial for Autotools.

This tutorial covers:

It targets people familiar with Unix development (i.e., basic knowledge of shell, make, C, and Unix is assumed) who want to learn using these tools, or simply understand their purpose.

The Tutorial

These files are released under the Creative Commons Attribution-ShareAlike 2.0 license. However trivial source code examples displayed in this tutorial (such as the C files, Makefile.am, and configure.ac of all the amhello projects) can be reused as if they were in the public domain.

Creative Commons License

Feedback

I welcome suggestions and corrections for this tutorial (send them to adl@gnu.org).

However, please, do not mail me any generic question about the Autotools. If you cannot find the answer to your question in the manuals or on the web, there are a lot of mailing lists where you will get help (and faster than writing to me), just pick the most appropriate:

autoconf@gnu.org questions and discussions about Autoconf
bug-autoconf@gnu.org bug reports about Autoconf
automake@gnu.org questions and discussions about Automake
bug-automake@gnu.org bug reports about Automake
libtool@gnu.org questions and discussions about Libtool
bug-libtool@gnu.org bug reports about Libtool
bug-gnu-gettext@gnu.org bug reports about Gettext
translation-i18n@lists.sourceforge.net methodology questions around internationalization, and discussions of translator tools (not only Gettext)
mentors@gnu.org help list for new maintainers of GNU packages (requires subscription)

ChangeLog Atom

2010-05-16 (162 slides = 556 pages)

Update to Libtool 2.2.6b and use LT_INIT instead of AC_PROG_LIBTOOL. Update to Autoconf 2.65 and Automake 1.11.1. Replace the obsolete AC_TRY_COMPILE by AC_COMPILE_IFELSE in the mkdir() macro example.

Jack Kelly suggested using foreign -Wall -Werror instead of -Wall -Werror foreign because the foreign option may alter the -W settings. Lorenzo Bettini pointed out that HP's test drive had been closed, so I'm now suggesting to Google for "free shell account" instead of pointing to specific services. Laurent Lyaudet reported several typos. Nicolas Cherel suggested to highlight a change in an example, because he did not notice it on first read.

2008-02-21 (162 slides = 557 pages)
Follow Roy Shea's suggestion to use AM_INIT_AUTOMAKE([-Wall -Werror foreign]) everywhere for consistency. It was missing in two examples.
2008-01-10 (162 slides = 557 pages)
These web pages moved to a new location. I've updated the slides to newer versions of the Autotools (that just means bumping the numbers, nothing else changed).
2006-08-12 (162 slides = 557 pages)

Fix the the Cross Compilation slide. It is still important to specify --build in addition to --host, and the handout version needs two pages.

I have also posted a first draft of an introductory chapter for the Automake manual, it mostly covers the first part of this tutorial.

2006-06-27 (162 slides = 557 pages)
Adjust the Standard File System Hierarchy slide to Autoconf 2.60.
2006-05-15 (162 slides = 557 pages)
This tiny update fixes one typo reported by Michael Brandt, and another one by Gregory Pakosz.
2006-04-15 (162 slides = 557 pages)
Some remarks from Ralf Wildenhues: the important change is that the tutorial now always puts libraries in _LDADD or _LIBADD, even -l and -L options. The position of _LDFLAGS on the link line doesn't make it appropriate for static libraries; it is better used for other link options.
2006-03-26 (162 slides = 557 pages)
A typo reported by Benoit Sigoure, and a new slide about spacing in M4.
2006-03-13 (161 slides = 553 pages)
Some corrections by Chris Pickett, and a leftover from Akim Demaille.
2006-03-05 (160 slides = 552 pages)
A few more minor corrections, and a brand new final slide.
2006-03-04 (159 slides = 549 pages)
Akim Demaille caught a few errors, and bundled them with more suggestions. Two noteworthy improvements in this new version, based on his suggestions: display the new lines in the M4 example, and split the definition of AX_FUNC_MKDIR_ONE_ARG in two macros (one for the test and the other for the caching and definitions).
2006-02-27 (158 slides = 545 pages)
In case you want to track updates to this tutorial, this ChangeLog is now also available as an Atom Feed Atom.
2006-02-22 (158 slides = 545 pages)

Use #include <config.h> instead of #include "config.h" as suggested by the Autoconf manual and pointed out by Florian Stoehr. Upgrade to Gettext 0.14.5, Libtool 1.5.22, and Automake 1.9.6 (no change needed).

Upgrade the drawing macros used in the LaTeX source to the brand new version 1.00 of pgf (the graphic package that comes with beamer). The change was hard since I couldn't find how to define the control points of the curved arrows in the same way as in version 0.67, but the resulting source is now much more readable.

2005-06-27 (158 slides = 545 pages)
A couple of minor corrections from Cyril Martin and Dorival Pedroso.
2005-05-23 (158 slides = 545 pages)
Upgrade to Gettext 0.14.4 and Libtool 1.5.18. Show an example setup for nested packages. Remove the stub-section about autom4te, this is too advanced.
2005-04-26 (155 slides = 538 pages)
I'm now building a handout version, with most of the animations removed, for printing. The M4 explanation is not really understandable in this version, since it relies on animations.
2005-04-03 (155 slides = 538 pages)
More corrections from Bruno Haible, plus a new slide: Recommendations for Writing Autoconf Macros.
2005-03-18 (154 slides = 534 pages)
Use AC_CONFIG_AUX_DIR([build-aux]) instead of AC_CONFIG_AUX_DIR([tools]), since we now advocate the former.
2005-03-15 (154 slides = 534 pages)
Update to Gettext 0.14.3, plus corrections from Bruno Haible.
2005-03-14 (154 slides = 537 pages)
Complete the Localization subsection. I think this will close the Gettext section.
2005-03-09 (142 slides = 499 pages)

Autotools versions are displayed at the very beginning, (1) to invite newcomers to start with up-to-date tools, and (2) to help people judge when the tutorial has become obsolete.

Added a slide, Lost?, at the end of Part 2, following an advice read in Mathematical Writings (Donald E. Knuth, Tracy L. Larrabee, and Paul M. Roberts):

Don's wife commented that one thing she always needs to know is “How do I get out of a mess if I do something wrong?” Don said that this is something manuals almost never explain—perhaps it never occurs to their authors that somebody will eventually want to stop playing with their program.

(Although completely unrelated to Autotools, Mathematical Writings is pleasant and instructive reading. You can find a PDF version of the initial report on-line.)

2005-03-08 (140 slides = 495 pages)
Some corrections to the Gettext slides from Bruno Haible.
2005-03-05 (140 slides = 495 pages)
More slides for Gettext, finishing the internationalization of Hello World.
2005-02-28 (133 slides = 477 pages)

Applied two patches to Beamer's classes to fix the slide count glitch mentioned yesterday and to display parts in the PDF bookmarks.

Seven more slides for the Gettext section: the beginning of a start-to-finish Hello World.

2005-02-27 (183 slides = 461 pages)

Do not use aclocal -I m4 in the Libtool example. This is only useful for the upcoming Libtool 2.0, and would cause distcheck failures in this little example (can't use AC_CONFIG_AUX_DIR with an empty directory).

First two slides of the Gettext section.

I just realized that the slides are not numbered with consecutive numbers. Where are slides 7, 9, 11, 21, ..., 180? It seems the frame counter is incremented before each fragile frame.

2005-02-12 (180 slides = 450 pages)
A Libtool section appeared. However it doesn't cover things like nested convenience libraries or libltdl. Maybe it should.
2005-02-09 (157 slides = 409 pages)
Added an Extending Automake Rules slide, at the end of the Using Automake section.
2005-02-06 (156 slides = 404 pages)
Completed a section about writing and managing local Autoconf macros. (Discussing aclocal -I m4 is a requirement before talking about Libtool and Gettext.)
2005-01-30 (140 slides = 371 pages)
Since this page has been mentioned a few times already, it's time to start a ChangeLog so people know what changed. Let me also thank Akim Demaille, Jim Meyering, Karl Berry, and Noah Misch for comments and corrections on earlier versions (I started working on this on 2004-12-12).

Comments

There is at least three reasons why I started writing this tutorial.

  1. First, several people around my team here at LIP6 suggested that I do a presentation of the Autotools (or more precisely Automake, it seems to be what people want to learn first). This explains the format of this tutorial: a set of slides that might seem more appropriate for a lecture than for self teaching. However I've kept that latter purpose on mind, so I hope the main material will be self-explanatory.
  2. Second, I've always wanted to see the GNU Build System documented from the user point of view somewhere. (Right now I think this should be done in the Automake manual for the sake of a better place.) This is unfortunately not documented anywhere (the GNU Coding Standards are not really user-oriented), so people do not know all they can do, and most importantly package maintainers do not fully understand the purpose of some features and the consequences of some of their setups.
  3. Finally, the Automake manual lacks an introduction, and I'm hoping that I'll be able to reuse parts of this tutorial to do so. (Actually the whole manual could use an overhaul, but this is a daunting task and I thought writing this tutorial could bring useful ideas.) Also the Hello example that is currently in the manual is completely out-of-date.

In the course of preparing this tutorial, I have found the more dynamic nature of such presentation to be an advantage over a still article. For instance I'm quite proud of the presentation of M4 that shows how M4 processes its input step by step. Describing how M4 works using sentences is not terribly difficult, however my experience is that people who read these sentences will not really understand them. Maybe they think “Oh, so it's just a macro processor” and then assume it works like C's with a slightly different syntax. I remember this happened to me when I learned Autoconf. Only after my first incomprehensible Autoconf error did I start wondering what underquoted meant...

Other Resources

Warning

I have yet to sort this collection of links. Beware that some of these may discuss old Autotools versions such as Autoconf 2.13 and Automake 1.4. Syntaxes and conventions have improved quite a bit with Autoconf 2.50 and Automake 1.7. However even these versions should be regarded as relics.

While old syntaxes will usually still work, it is a bad idea to use them in a new project. Better start with up-to-date Autotools and learn today's usages.

As an easy test, if a document uses configure.in instead of configure.ac, it is most likely discussing older releases. This does not mean the contents are meaningless, but you should worry before copying examples.

GNU Autoconf, Automake, and Libtool
(book in English) http://sources.redhat.com/autobook/
Overhauling Amd for the '00s: A Case Study of GNU Autotools
(paper in English) http://www.am-utils.org/docs/autotools/autotools.pdf
Practical Auto-confiscation
(slides in English) http://users.actcom.co.il/~oron/oron/docs/autotools.pdf
Learning the GNU development tools
(manual in English) http://autotoolset.sourceforge.net/tutorial.html
autotut: Using GNU auto{conf,make,header}
(document in English) http://seul.org/docs/autotut/
The GNU Build System
(slides in English) http://www.netsplit.com/text/gnu-build-system/
Autoconf/Automake Basics
(slides in English) http://www.lugod.org/presentations/autotools/presentation/autotools.pdf
GNU autotools pour la publication et le déploiement de logiciels
(slides in French) http://www.codiciel.fr/gestion/autotools/cours_2004/autotools.pdf
autotools: Herramientas para la creación de proyectos Open Source
(paper in Spanish) http://www.ubiobio.cl/~gpoo/documentos/autotools.pdf
A Very Short Introduction to Autotools
(paper in English) http://wilma.vub.ac.be/~se5-0203/tutorials/Autotools.pdf
Software Portability with GNU Autotools
(slides in English) http://www.cs.uu.nl/docs/vakken/swe/slides/SWE-Autotools.pdf
Outils de configuration GNU
(slides in French) http://supports.goualard.free.fr/files/master-alma/outils/cours-configuration-dess-gi.pdf
Using Automake and Autoconf with C++
(web page in English) http://www.openismus.com/documents/linux/automake/automake.shtml
Autotools Tutorial for Beginners
(web site in English) http://vindaci.members.sonic.net/cbreak/projects/autotools/
Building a GNU Autotools Project
(web page in English) http://inti.sourceforge.net/tutorial/libinti/autotoolsproject.html
Using The AutoTools
(web page in English) http://www.eglug.org/node/621
Autotools Tutorial
(paper in English) http://wilma.vub.ac.be/~se2/docs/autotools.ps
Autoconf & Automake
(slides in French) http://etudiant.epita.fr/~clavei_t/autotools/autotools.ps
Autoconf / Automake tutorial
(web page in Japanese) http://larse-gtk.hp.infoseek.co.jp/automake.html
Anjuta advanced tutorial
(web page in English) http://www.anjuta.org/anjuta.php?page=documentations&subpage=documents/C/anjuta-advanced-tutorial/index.html
Índice Autoconf y Automake
(web site in Spanish) http://mutation2k.webcindario.com/autoconf/autoconf.php
Autoconf/Automake
(web site in French) http://www.programmationworld.com/site/Cours.asp?Action=cours&numero=130
The GNU Build System
(web page in English) http://www.adp-gmbh.ch/blog/2004/december/1.html
Simplifying program packaging with the GNU Build System
(web page in English) http://tools.devchannel.org/devtoolschannel/03/11/14/1615230.shtml?tid=46
Quick Guide to the GNU Build System
(web page in English) http://freedomink.org/node/100
Lecture about the GNU Autotools
(slides in English) http://vipe.technion.ac.il/~shlomif/lecture/Autotools/
libglade, Gtk+, GNU autotools: by example
(web page in English) http://adammonsen.com/tut/libgladeTest.html
Finding and Defining Features
(article in English) http://www.linux-mag.com/2002-12/compile_01.html
GNU Autotools
(slides in French) http://www.raphael.poss.name/articles/autotools
Using static and shared libraries across platforms
(web page in English) http://www.fortran-2000.com/ArnaudRecipes/sharedlib.html
Automake / Autoconf
(web page in French) http://www.enseeiht.fr/lima/irt/membres/boyer/Automake-Autoconf/Automake.htm
A brief introduction to Autoconf
(web page in English) http://mi.eng.cam.ac.uk/~er258/code/autoconf/index.html
Autoconf, Automake
(slides in French) http://www.infres.enst.fr/~dax/polys/configure/