.. meta::
:description: An Autotools Tutorial, covering Autoconf, Automake,
Libtool, and Gettext.
====================
Autotools Tutorial
====================
This is the home of my tutorial for Autotools.
This tutorial covers:
* The GNU Build System
* The GNU Autotools:
* Autoconf_
* Automake_
* Libtool_
* Gettext_
.. _Autoconf: http://www.gnu.org/software/autoconf/
.. _Automake: http://sources.redhat.com/automake/
.. _Libtool: http://www.gnu.org/software/libtool/
.. _Gettext: http://www.gnu.org/software/gettext/
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
============
* `The tutorial in PDF`__
* `Handout version in PDF`__ (4 slides per pages without animations,
for printing)
* `LaTeX sources`__ (using the Beamer_ class)
__ dl/autotools.pdf
__ dl/autotools-handout-4.pdf
__ dl/autotools.tex
.. _Beamer: http://latex-beamer.sourceforge.net/
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.
__ by-sa-2.0_
.. image:: http://creativecommons.org/images/public/somerights20.png
:height: 31
:width: 88
:alt: Creative Commons License
:target: by-sa-2.0_
.. _by-sa-2.0: http://creativecommons.org/licenses/by-sa/2.0/
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:
__ automail.html
.. list-table::
:widths: 30 70
* - 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_)
.. _subscription: http://lists.gnu.org/mailman/listinfo/mentors
ChangeLog |Atom|
----------------
.. |Atom| image:: img/Livemark.png
:height: 16
:width: 16
:target: atomfeed_
.. role:: bug
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.
__ http://news.gmane.org/find-root.php?message_id=%3c2006%2d08%2d12%2d23%2d45%2d50%2b6381%2badl%40gnu.org%3e
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.
.. _Michael Brandt: http://www.michabrandt.de/
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.
.. _Ralf Wildenhues: http://wissrech.iam.uni-bonn.de/people/wildenhues.html
2006-03-26 (162 slides = 557 pages)
A typo reported by `Benoit Sigoure`_, and a new slide about spacing in M4.
.. _Benoit Sigoure: http://tsunanet.net/
2006-03-13 (161 slides = 553 pages)
Some corrections by `Chris Pickett`_, and a leftover from `Akim Demaille`_.
.. _Chris Pickett: http://www.sable.mcgill.ca/~cpicke/
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|.
.. _atomfeed: autotools.atom
.. _Atom Feed: atomfeed_
2006-02-22 (158 slides = 545 pages)
Use ``#include `` 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`__.
__ http://lists.gnu.org/archive/html/bug-gnulib/2005-03/msg00106.html
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 |MW|_ (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, |MW|_ is pleasant and
instructive reading. You can find a PDF version of the initial
report `on-line`__.)
__ http://tex.loria.fr/typographie/mathwriting.pdf
.. |MW| replace:: :title-reference:`Mathematical Writings`
.. _MW: http://www-cs-faculty.stanford.edu/~knuth/klr.html
.. |---| unicode:: U+02014 .. em dash
:trim:
.. |``| unicode:: U+0201C .. left double quote
:rtrim:
.. |''| unicode:: U+0201D .. right double quote
:ltrim:
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.
__ http://cvs.sourceforge.net/viewcvs.py/latex-beamer/latex-beamer/base/beamerbaseframe.sty?r1=1.48&r2=1.50&diff_format=u
__ https://sourceforge.net/tracker/?func=detail&aid=1093808&group_id=92412&atid=600662
2005-02-27 (:bug:`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 (:bug:`180 slides` = 450 pages)
A Libtool_ section appeared. However it doesn't cover things like
nested convenience libraries or libltdl_. Maybe it should.
.. _libltdl: http://www.gnu.org/software/libtool/manual.html#Using-libltdl
2005-02-09 (:bug:`157 slides` = 409 pages)
Added an *Extending Automake Rules* slide, at the end of
the *Using Automake* section.
2005-02-06 (:bug:`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 (:bug:`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).
.. _Akim Demaille: http://www.lrde.epita.fr/cgi-bin/twiki/view/Main/AkimDemaille
.. _Bruno Haible: http://www.haible.de/bruno/
.. _Jim Meyering: http://meyering.net/
.. _Karl Berry: http://www.freefriends.org/~karl/
.. _Noah Misch: http://www.cs.caltech.edu/~noah/
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`_.
.. _LIP6: http://www.lip6.fr/
.. _team: http://www-src.lip6.fr/
.. _Automake manual: http://sources.redhat.com/automake/automake.html
.. _GNU Coding Standards: http://www.gnu.org/prep/standards/
.. _completely out-of-date: http://lists.gnu.org/archive/html/bug-hello/2004-12/msg00008.html
.. _lacks an introduction: http://sources.redhat.com/ml/automake/2004-01/msg00215.html
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...
.. _M4: http://www.gnu.org/software/m4/
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/