Autoreconfing packages - A Maintainers' Guide

Autoreconfing on build is good practice in Debian. There used to be good reasons to stick with the autotools files shipped in the upstream tarball (mostly incompatibility with newer versions), but these days good forward compatibility and the advantages of getting the latest updates for new architectures or other fixes means that autoreconfing on build should be the default in packages.

General reasoning for autoreconfing

744915 has very relevant discussion.

dh-autoreconf and autotools-dev

The autotools-dev package supplies current (system-wide) versions of config.sub and config.guess.

The dh-autoreconf package supplies dh module/debhelper/cdbs commands to run autoreconf and restore the original source files on clean. These commands are run by default when using the dh sequencer since debhelper compatibility level 10.

In most cases, running using autoreconf (by using dh-autoreconf) already updates config.sub and config.guess. However, in some cases as explained below, autoreconf does not update config.sub and config.guess. To deal with these cases, the debhelper package includes the dh_update_autotools_config command since version 9.20160115 to replace (possibly outdated) config.{sub,guess} files in the source package with the ones from the autotools-dev package. This command is enabled by default when using the dh sequencer, so you normally do not need to worry about this.

Most packages use automake and/or libtool as well as autoconf, in which case using dh-autoreconf is all that's needed.

automake, libtool and autotools-dev all contain config.{sub,guess} files. autoconf, cdbs, debhelper and dh-autoreconf don't include these files. So this means that using dh-autoreconf on packages which only use autoconf (but not automake) (even with debhelper or CDBS) is not enough to update config.{sub,guess}. In this case you need to use both dh-autoreconf and autotools-dev.

Which tools does my package use?

If your package has a configure.ac file then it uses autoconf. (Very old packages may have configure.in instead. If you see configure.in, ask upstream to rename this to configure.ac. configure.in is deprecated, and Autoconf has supported configure.ac for quite some time.)

If your package has a Makefile.am file then it uses automake.

If the configure.ac file contains AC_PROG_LIBTOOL or AM_PROG_LIBTOOL (older) or LT_INIT (newer), the package uses Libtool.

If Makefile.am is present, Makefile.in normally will be as well. This file will be regenerated by autoreconf. The presence of Makefile.in (or some other variation of makefile ending in *.in) without Makefile.am normally means that the package uses Autoconf but not Automake, but it could indicate that some other build system entirely is in use.

Using dh-autoreconf

This is normally the right thing to use. See above for exceptions.

dh-using packages

dh-autoreconf is enabled by default since debhelper compatibility level 10 (and the debhelper package Depends on dh-autoreconf since version 9.20160402). For lower compatibility levels:

dh $@ --with autoreconf

debhelper packages

configure:
        dh_autoreconf
        ./configure ...

clean:
        <package clean commands>
        dh_autoreconf_clean
        dh_clean

CDBS-using packages

include /usr/share/cdbs/1/rules/autoreconf.mk

Source in subdir

If the configure and autotools files are in a subdir, then plain dh_autoreconf will often not work. Add a file debian/autoreconf containing the name of the subdir (or subdirs) it should be run in.

In debhelper compat 10, dh_autoreconf will use "--sourcedirectory" if passed.

Updating macros

Autoreconf can be picky. Many packages will 'just work', but especially older code may need macros updating to make it work. Lots of macros will need updating if you want to get rid of all the warings. This is good practice but things work pretty well in my experience if you don't bother.

The most common warning by far is about underquoted macros or macro arguments from Autoconf. Sometimes this can even cause fatal errors. Often, you can leave these unfixed without any negative effects, but if you do want to work with upstream on eliminating warnings, or if you see errors, you may want to consider fixing macro quoting. The rule of thumb (per the Autoconf manual) is one pair of quotes ([]) around each argument to every macro call. In other words, instead of:

AC_CHECK_TYPES(ssize_t, , , #include <sys/types.h>)

the Autoconf code should look like:

AC_CHECK_TYPES([ssize_t], [], [], [#include <sys/types.h>])

Each argument to the macro gets one and only one level of quoting.

Another common problem with older configure.ac files is not calling AM_PROG_AR. This is a problem due to a backwards incompatibility in Automake: Automake 1.11 does not contain that macro, but Automake 1.12 requires that it be called. To fix this problem, add:

m4_ifdef([AM_PROG_AR], [AM_PROG_AR])

near the top of configure.ac.

Setting 'foreign' strictness for automake stops silly things like 'not having a NEWS file' being a fatal error. https://www.gnu.org/software/automake/manual/html_node/Strictness.html

AM_INIT_AUTOMAKE([foreign])

AUTOMAKE_OPTIONS = foreign

Using autotools-dev

autotools-dev provides /usr/share/misc/config.sub and /usr/share/misc/config.guess files which are up to date. This is enough to update packages which only use autoconf (and not automake, libtool, autoheader etc). When those other packages are used you should really use dh-autoreconf as that will also update necessary libtool and automake files/macros which is needed for some architectures. Also, in general updating config.{sub,guess} without autoreconfing is not guaranteed to work in the long term (although in practice it is as actually very safe and generally works fine, even when the source is a decade old).

For packages which use autoconf, but not automake, libtool, autoheader, you will actually need to use both dh-autoreconf _and_ replace config.{sub,guess} with the versions from the autotools-dev package. These need to be copied into the source over any copies in there before configure is run.

This can be done manually (remember to get all copies), or using the helpers. See below for your sort of package.

For dpkg source format 3 packages you need to restore the original files on clean so that dpkg-soure doesn't complain of changed source files.

dh-using packages

Since debhelper/9.20160115, dh includes a command called dh_update_autotools_config which does this for you and is enabled by default when using the dh sequencer.

For earlier versions, you will need:

dh $@ --with autotools-dev

debhelper packages

When using debhelper >=9.20160115:

For ealier versions:

configure:
        dh_autotools-dev_updateconfig
        ./configure ...

clean:
        <package clean commands>
        dh_autotools-dev_restoreconfig
        dh_clean

CDBS-using packages

This it - it's automatically used if present. Note that because CDBS recommends autotools-dev this will magically work by default if you just test it on your machine, but when run in a buildd (where recommends are not installed) autotools-dev will be missing unless _your_ package depends on it.

Non-debhelper packages

configure:
        cp -f /usr/share/misc/config.sub .
        cp -f /usr/share/misc/config.guess .