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.

General questions
*****************

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).

  * Autoconf helps create portable configure and testsuite scripts.

  * Automake helps create portable Makefiles supporting all the targets documented by the GNU Coding Standards (The GNU Coding Standards).

  * Libtool helps create and use shared libraries portably.

  * Gnulib is intended to be the canonical source for most of the important ``portability'' and/or common files for GNU projects.

Together, they make up the GNU Build System (The Automake Manual).

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.

Where can I get more information about these tools?
===================================================

     The home page for GNU Autoconf (http://www.gnu.org/software/autoconf/).
     The home page for GNU Automake (http://www.gnu.org/software/automake/).
     The home page for GNU Libtool (http://www.gnu.org/software/libtool/).
     The home page for GNU gnulib (http://www.gnu.org/software/gnulib/).

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

Beside, there are many Tutorials.

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 (http://git-scm.com/) source code management.  A wiki page on Savannah (http://savannah.gnu.org) documents how to use Git (http://savannah.gnu.org/maintenance/UsingGit). 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 (http://www.gnu.org/software/libtool).

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 (http://lists.gnu.org/mailman/listinfo/automake/) in order to write there.  Past discussions can be found in the list archives (http://lists.gnu.org/archive/html/automake/).

If you like, you can send a patch against the source of the current version of the FAQ (http://www.gnu.org/software/automake/faq/autotools-faq.texi), written in Texinfo.

How do I report a bug?
======================

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

  * For Autoconf, write to bug-autoconf@gnu.org; list archives can be found at http://lists.gnu.org/archive/html/bug-autoconf/.

  * For Automake, see the bug reporting instructions (http://www.gnu.org/software/automake/manual/html_node/Reporting-Bugs.html), then write to bug-automake@gnu.org; list archives can be found at http://lists.gnu.org/archive/html/bug-automake/. Messages that do not reply to existing threads create new bugs in the debbugs GNU bug tracker for Automake (http://debbugs.gnu.org/automake).

  * For Libtool, write to bug-libtool@gnu.org; list archives can be found at http://lists.gnu.org/archive/html/bug-libtool/.

  * For gnulib, write to bug-gnulib@gnu.org; list archives can be found at http://lists.gnu.org/archive/html/bug-gnulib/.

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.

What are the differences to other build systems?
================================================

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

Why is everything so complicated?
=================================

TODO

Getting started
***************

What tutorials exist?
=====================

Alexandre Duret-Lutz' Autotools Tutorial (http://www.lrde.epita.fr/~adl/autotools.html), 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 (The Automake Manual) chapter of the Automake manual is a shortened version of Alexandre's tutorial.

All you should really know about Autoconf and Automake (http://smalltalk.gnu.org/blog/bonzinip/all-you-should-really-know-about-autoconf-and-automake), a very short and concise tutorial from Paolo Bonzini.

Autotools Mythbuster (http://www.flameeyes.eu/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 (http://www.freesoftwaremagazine.com/books/autotools_a_guide_to_autoconf_automake_libtool) is a book introducing Autotools, from John Calcote.

The Goat Book or Autobook (http://sources.redhat.com/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 (The Automake Manual) in the Automake manual.

GNU hello (http://www.gnu.org/software/hello/), the (not so small) example package using all kinds of GNU infrastructure.

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 (GNU gnulib)

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.16.tar.gz
     wget http://ftp.gnu.org/gnu/autoconf/autoconf-2.68.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.16.tar.gz | tar xvf -
     gzip -dc autoconf-2.68.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.16
     ./configure -C --prefix=$myprefix && make && make install
     cd ../autoconf-2.68
     ./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.

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 (gnulib), see Modified imports (gnulib).

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

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 (The Automake Manual) in the toplevel Makefile.am file, and AC_CONFIG_MACRO_DIR (The Autoconf Manual) 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 (The Autoconf Manual).

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 (The Autoconf Manual)

Integrating libtool (The Libtool Manual)

It can get even more complicated: acconfig Header (The Autoconf Manual)

TODO: link to the nice online images?

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:

  * Write the sub/foo/Makefile.am file itself.

  * Edit the next higher-up Makefile.am and add the relative directory in its SUBDIRS; i.e., in this case, either add foo to the SUBDIRS variable in sub/Makefile.am:

          ## sub/Makefile.am
          SUBDIRS = ...

          SUBDIRS += foo

     or add sub/foo to the SUBDIRS variable in the toplevel Makefile.am if there is no intermediate sub/Makefile.am (see Subdirectories (The Automake Manual)).

  * Add the line AC_CONFIG_FILES([sub/foo/Makefile]) to the configure.ac file (see Requirements (The Automake Manual)).

     A few large package trees use more than one configure.ac file, i.e., they contain subpackages.  In this case, all file names above are meant relative to the nearest higher-up configure.ac file (see Subpackages (The Automake Manual)).

Then, rerunning make in the build directory should do the right thing unless you have rebuild rules disabled (see maintainer-mode (The Automake Manual)); alternatively, run autoreconf -v in the toplevel source directory.  See amhello Explained (The Automake Manual), 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 (The Automake Manual)).

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

TODO:

AC_SUBST, see Setting Output Variables (autoconf), see General Operation (automake).

AC_DEFINE, see Defining Symbols (autoconf).

How do I override Makefile macros set by automake?
==================================================

TODO:

AC_SUBST

setting in Makefile.am

AUTOMAKE_OPTIONS = -Wno-override -Wno-syntax

How can I install software below my home directory?
===================================================

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

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 (GNU gnulib)

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 (The Autoconf Manual)).

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

TODO

either quote them by using more brackets, or use Quadrigraphs (The Autoconf Manual)

Libtool-related questions
*************************

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).

Libtool library used but LIBTOOL is undefined
=============================================

TODO

libtool reorders link flags
===========================

TODO

Libtool warning seems to be moved
=================================

TODO

Why does libtool relink files during make install?
==================================================

TODO

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.

Tips and Tricks
***************

How can I speed up configure?
=============================

TODO:

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

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

As developer:

  * Do not add any tests to configure.ac your code isn't prepared to deal with anyway.

  * Do not use obsolete or obsolescent tests like AC_C_CONST.

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.

Does Automake support nonrecursive Makefiles?
=============================================

TODO: Yes.

Alternative (The Automake Manual)

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

TODO

How do I enable cross compilation reliably?
===========================================

TODO

pass both --host and --build to configure

How do I build packages with MSVC?
==================================

TODO

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

TODO

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

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

     eval configure "$ac_configure_args"

Why should config.h not be installed?
=====================================

Here's a detailed explanation: Where to stick config.h (http://inaugust.com/post/68).

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

  * Use a hand-written config header template file with only those defines that you absolutely need.  Pass it as second (or further) argument to AC_CONFIG_HEADERS.  autoheader will only generate a header template for the first argument. see Header Templates (The Autoconf Manual).

  * Use the AX_PREFIX_CONFIG_H macro from The Autoconf Macro Archive (http://www.gnu.org/software/autoconf-archive/).

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