Autotools FAQ

Table of Contents


Next: , Up: (dir)

GNU Autotools FAQ

This document aims to answer the most frequently asked questions about the GNU Autotools (Autoconf, Automake, and Libtool).

The master location of this document is available online at http://www.gnu.org/software/automake/faq/autotools-faq.html, generated from http://www.gnu.org/software/automake/faq/autotools-faq.texi.

Copyright © 2011 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License.”

All example code shown in this FAQ is in the public domain.


Next: , Previous: Top, Up: Top

1 General questions


Next: , Up: General questions

1.1 What are the “Autotools”?

The name GNU Autotools commonly refers to the software packages Autoconf, Automake, and Libtool. They consist of a number of programs used by developers, among them autoreconf, autoconf, autoheader, autoscan (which come from the Autoconf package), aclocal and automake (which come from the Automake package), and libtoolize (from the Libtool package).

Together, they make up the GNU Build System.

Often, the following tools are used at the same time: gnulib-tool (from the gnulib package), gettextize and autopoint (from the gettext package).

Under the hood, the autotools use a helper script named autom4te which itself calls out to GNU M4.


Next: , Previous: What are the ``Autotools''?, Up: General questions

1.2 Where can I get more information about these tools?

     The home page for GNU Autoconf.
     The home page for GNU Automake.
     The home page for GNU Libtool.
     The home page for GNU gnulib.

The tools have manuals, see Where is the official documentation?, and also individual FAQ chapters in the manual: see the Autoconf FAQ, see the Automake FAQ, see the Libtool FAQ.

Beside, there are a lot of Tutorials.


Next: , Previous: Where can I get more information about these tools?, Up: General questions

1.3 Where can I get the latest versions of these tools?

Usually, from the software distribution of your system. But you can also install them yourself, if there is a newer release available. If you build them yourself, it is recommended to install them all under the same prefix (see How can I install software below my home directory?).

The most recent stable releases can be found here:

     http://ftp.gnu.org/gnu/autoconf/
     http://ftp.gnu.org/gnu/automake/
     http://ftp.gnu.org/gnu/libtool/

Development is done with Git source code management. A wiki page on Savannah documents how to use Git. The development versions of the Autotools can be found here:

     http://savannah.gnu.org/git/?group=autoconf
     http://savannah.gnu.org/git/?group=automake
     http://savannah.gnu.org/git/?group=libtool
     http://savannah.gnu.org/git/?group=gnulib

Nightly snapshot tarballs of the Libtool sources are linked from the Libtool home page.


Next: , Previous: Where can I get the latest versions of these tools?, Up: General questions

1.4 How do I add a question to this FAQ?

Simply write an email to the automake@gnu.org mailing list. You do not need to be subscribed in order to write there. Past discussions can be found in the list archives.

If you like, you can send a patch against the source of the current version of the FAQ, written in Texinfo.


Next: , Previous: How do I add a question to this FAQ?, Up: General questions

1.5 How do I report a bug?

Each of the tools has separate bug reporting lists and list archives:

TODO

If you are unsure where to write to, choose one of the lists. It is not a big problem if you choose the wrong one, but please do not post your report to multiple lists in several separate mails.


Next: , Previous: How do I report a bug?, Up: General questions

1.6 What are the differences to other build systems?

TODO: Compare with CMake, waf, scons, ...


Previous: What are the differences to other build systems?, Up: General questions

1.7 Why is everything so complicated?

TODO


Next: , Previous: General questions, Up: Top

2 Getting started


Next: , Up: Getting started

2.1 What tutorials exist?

Alexandre Duret-Lutz' Autotools Tutorial, a very long and detailed tutorial in presentation form, also has a long list of other online tutorials and online Autotools resources.

The Autotools Introduction chapter of the Automake manual is a shortened version of Alexandre's tutorial.

All you should really know about Autoconf and Automake, a very short and concise tutorial from Paolo Bonzini.

Autotools Mythbuster, a longer guide also explaining some newer features, from Diego E. “Flameeyes” Pettenò.

Autotools: a practitioner's guide to Autoconf Automake and Libtool is a book introducing Autotools, from John Calcote.

The Goat Book or Autobook, officially titled “GNU Autoconf, Automake, and Libtool”, is a printed and online introduction into all three tools, from 2000, written by Gary V. Vaughan, Ben Elliston, Tom Tromey, and Ian Lance Taylor.

There are many more online tutorials and resources, especially for some specific build environments.

Example packages can be found here:

A Small Hello World Example with Automake in the Automake manual.

GNU hello, the (not so small) example package using all kinds of GNU infrastructure.


Next: , Previous: What tutorials exist?, Up: Getting started

2.2 Where is the official documentation?

Each of the tools has a separate manual:

     The Autoconf Manual
     The Automake Manual
     The Libtool Manual
     The gnulib Manual


Next: , Previous: Where is the official documentation?, Up: Getting started

2.3 How do I install the Autotools (as user)?

If the Autotools are not installed on your system, or the installed versions are too old, and you do not have the rights to install or update them globally, then you can install them under your home directory as follows:

     # Assume we want to install them below $HOME/local.
     myprefix=$HOME/local
     
     # Ensure the tools are accessible from PATH.
     # It is advisable to set this also in ~/.profile, for development.
     PATH=$myprefix/bin:$PATH
     export PATH
     
     # Do the following in a scratch directory.
     wget http://ftp.gnu.org/gnu/m4/m4-1.4.14.tar.gz
     wget http://ftp.gnu.org/gnu/autoconf/autoconf-2.64.tar.gz
     wget http://ftp.gnu.org/gnu/automake/automake-1.11.1.tar.gz
     wget http://ftp.gnu.org/gnu/libtool/libtool-2.4.tar.gz
     gzip -dc m4-1.4.14.tar.gz | tar xvf -
     gzip -dc autoconf-2.64.tar.gz | tar xvf -
     gzip -dc automake-1.11.1.tar.gz | tar xvf -
     gzip -dc libtool-2.4.tar.gz | tar xvf -
     cd m4-1.4.14
     ./configure -C --prefix=$myprefix && make && make install
     cd ../autoconf-2.64
     ./configure -C --prefix=$myprefix && make && make install
     cd ../automake-1.11.1
     ./configure -C --prefix=$myprefix && make && make install
     cd ../libtool-2.4
     ./configure -C --prefix=$myprefix && make && make install
     
     # If everything succeeded, you can delete the scratch directory again.


Next: , Previous: How do I install the Autotools (as user)?, Up: Getting started

2.4 What does ./bootstrap or ./autogen.sh do?

TODO

usually: call autotools commands to copy and generate a number of files. Often just autoreconf -vi.

gnulib provides a very elaborate bootstrap script, see VCS Issues, see Modified imports.

The name bootstrap is preferred over ‘autogen.sh’ as there also exists an independent software package named AutoGen.


Next: , Previous: What does ./bootstrap or ./autogen.sh do?, Up: Getting started

2.5 Which files are hand-written and which generated (and how)?

TODO

(Usually) hand-written:

configure.ac
Input file for Autoconf.
Makefile.am
Input file(s) for Automake.
acinclude.m4
m4/*.m4
Additional files containing Autoconf macros. The m4/ directory name is a common convention, set by ACLOCAL_AMFLAGS in the toplevel Makefile.am file, and AC_CONFIG_MACRO_DIR in the configure.ac file.

Generated on the developer system:

aclocal.m4
Usually generated by aclocal, contains additional Autoconf macros from Automake and third-party macro files. Some packages choose to not use aclocal and hand-write this file instead.
configure
Generated shell script that runs all the system tests and creates config.status.
config.h.in
Generated from autoheader, contains prototypes for C #defines, serves as template for the config.h file.
Makefile.in
Generated from automake (or hand-written in packages not using Automake).
autom4te.cache
Cache directory for autom4te, an internal helper script. This can safely be removed. see Autom4te Cache.
configure.scan
Output file of autoscan, which can serve as a prototype configure.ac file.

Installed from Autotools files:

ltmain.sh
Helper script from Libtool, installed by libtoolize.
install-sh
mkinstalldirs
mdate-sh
compile
depcomp
py-compile
ylwrap
Helper scripts from Automake, installed by automake --add-missing.

Generated on the user system (the one running configure) in the build directory tree (the one where configure is run from):

config.status
config.log
config.cache
config.h
Makefile

TODO: link to the various drawings in the manuals,
Making configure Scripts
Integrating libtool

It can get even more complicated: acconfig Header

TODO: link to the nice online images?


Next: , Previous: Which files are hand-written and which generated (and how)?, Up: Getting started

2.6 How do I add a Makefile.am file to an existing project?

     What do I need to do when I want to add a sub/foo/Makefile.am
     file to an existing project (in a recursive Makefile setup)?

In general, it takes three steps:

Then, rerunning make in the build directory should do the right thing unless you have rebuild rules disabled (see maintainer-mode); alternatively, run autoreconf -v in the toplevel source directory. See amhello Explained, for a small but complete example package.

In a nonrecursive Makefile project, depending on local convention, instead of the above three steps you would probably write a fragment file to be included in the toplevel Makefile.am:

     ## toplevel Makefile.am
     ...
     include sub/foo/fragment.am

Note that in this case you also need to use the relative subdirectory prefixes in file names used inside the fragment file (see Alternative).


Next: , Previous: How do I add a Makefile.am file to an existing project?, Up: Getting started

2.7 How do I communicate configure test results to a Makefile?

TODO:

AC_SUBST, see Setting Output Variables, see General Operation.

AC_DEFINE, see Defining Symbols.


Next: , Previous: How do I communicate configure test results to a Makefile?, Up: Getting started

2.8 How do I override Makefile macros set by automake?

TODO:

AC_SUBST

setting in Makefile.am

AUTOMAKE_OPTIONS = -Wno-override -Wno-syntax


Next: , Previous: How do I override Makefile macros set by automake?, Up: Getting started

2.9 How can I install software below my home directory?

     ./configure --prefix="$HOME/local"
     make
     make install


Next: , Previous: How can I install software below my home directory?, Up: Getting started

2.10 How do I add compiler or linker flags to the build system?

As user of an autotooled package:

     ./configure CPPFLAGS="-I$somewhere/include" LDFLAGS="-L$somewhere/lib"

As configure.ac author:

TODO

gnulib module ‘havelib’: Searching for Libraries


Next: , Previous: How do I add compiler or linker flags to the build system?, Up: Getting started

2.11 What does 'test "X$variable" = X' mean?

TODO

Weird way of writing test -z "$variable" that does not confuse the test builtins from old shells when $variable is ‘=’ or )’ (see Limitations of Builtins).


Previous: What does 'test "X$variable" = X' mean?, Up: Getting started

2.12 How do I use brackets [] in configure.ac scripts?

TODO

either quote them by using more brackets, or use Quadrigraphs


Next: , Previous: Getting started, Up: Top

3 Libtool-related questions


Next: , Up: Libtool-related questions

3.1 What are these .la files for and can I safely remove them?

TODO

portable encoding of static and shared library names and dependencies.

removing usually only works OK if done in directories which the runtime linker searches by default anyway (otherwise you might need to set LD_LIBRARY_PATH or an equivalent variable) and only on systems where the runtime linker loads indirect library dependencies automatically (includes GNU/Linux, GNU, Solaris).


Next: , Previous: What are these .la files for and can I safely remove them?, Up: Libtool-related questions

3.2 Libtool library used but LIBTOOL is undefined

TODO


Next: , Previous: Libtool library used but LIBTOOL is undefined, Up: Libtool-related questions

3.3 libtool reorders link flags

TODO


Next: , Previous: libtool reorders link flags, Up: Libtool-related questions

3.4 Libtool warning ‘seems to be moved

TODO


Next: , Previous: libtool warning 'seems to be moved', Up: Libtool-related questions

3.5 Why does libtool relink files during make install?

TODO


Previous: Why does libtool relink files during make install?, Up: Libtool-related questions

3.6 libtool fails with "X–tag=CXX: command not found"

TODO

somehow the output section of libtool.m4 does not get emitted into config.status. There has been an incompatibility in Autoconf's M4Sugar macros, and Libtool relied on one of those, not taking measures. It should work to use a new enough Autoconf.


Previous: Libtool-related questions, Up: Top

4 Tips and Tricks


Next: , Up: Tips and Tricks

4.1 How can I speed up configure?

TODO:

Use a cache file when developing: configure -C aka. configure --config-cache (see Cache Files).

Install a config.site file which presets common test results (see Site Defaults).

As developer:


Next: , Previous: How can I speed up configure?, Up: Tips and Tricks

4.2 How can I speed up make?

Build in parallel: make -jn, with n greater than 1.

As a developer: ensure your project parallelizes well, e.g., by using nonrecursive makefiles.


Next: , Previous: How can I speed up make?, Up: Tips and Tricks

4.3 Does Automake support nonrecursive Makefiles?

TODO: Yes.

Alternative


Next: , Previous: Does Automake support nonrecursive Makefiles?, Up: Tips and Tricks

4.4 How to enable support for modern bison (not yacc)?

TODO


Next: , Previous: How to enable support for modern bison (not yacc)?, Up: Tips and Tricks

4.5 How do I enable cross compilation reliably?

TODO

pass both --host and --build to configure


Next: , Previous: How do I enable cross compilation reliably?, Up: Tips and Tricks

4.6 How do I build packages with MSVC?

TODO


Next: , Previous: How do I build packages with MSVC?, Up: Tips and Tricks

4.7 How do I save/modify the arguments to configure?

TODO

either: very early after AC_INIT (see Initializing configure),

or: ac_configure_args, but note quoting rules: the whole thing is evaluated by the shell later:

     eval configure "$ac_configure_args"


Next: , Previous: How do I save/modify the arguments to configure?, Up: Tips and Tricks

4.8 Why should config.h not be installed?

Here's a detailed explanation: Where to stick config.h.

If you absolutely need to use #defines computed from configure in installed headers:


Previous: Why should config.h not be installed?, Up: Tips and Tricks

4.9 How do I use different C compilers in a Makefile.am?