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
- Just updating config.guess and config.sub isn't sufficient in many cases. For example, the most recent new architecture ppc64el also required libtool to be run.
- Autoconf has bugs. Refreshing automatically on build means that we can propagate fixes to those bugs. See the recently-discovered problem with detecting and enabling large file support.
- There is a strong theoretical argument in favor of regenerating the build machinery from source on the grounds that we want to build things from actual source and ensure that it's possible to modify the actual source, as opposed to requiring people doing modifications to potentially either debug Autoconf problems or hack on opaque shell scripts.
- By _far_ the largest piece of work for any new debian port is updating hundreds of packages to have newer autotools config information so that they will build for the new architecture. This is generally a trivial matter that should be automated, saving maintainers from doing uploads for each new arch, and saving porters from filing hundreds of very boring bugs, and allowing them to concentrate on the things that do actually need real porting work.
- Debian diff patches are reduced to 2 or 3 lines rather than 1-2 MB of configure/libtool file updates, improving clarity and using less archive space.
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:
- Build-Depend on dh-autoreconf
add --with autoreconf to the dh command:
dh $@ --with autoreconf
debhelper packages
Build-Depend on dh-autoreconf (only required when not Build-Depending on debhelper >= 9.20160402)
- Use dh_autoreconf in build/configure rule before running configure
- Use dh_autoreconf_clean in the clean rule (just before dh_clean)
configure:
dh_autoreconf
./configure ...
clean:
<package clean commands>
dh_autoreconf_clean
dh_clean
CDBS-using packages
- Build-depend on dh-autoreconf.
- debian/rules: include autoreconf.mk
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:
- Build-Depend on autotools-dev
- add --with autotools-dev to the dh command:
dh $@ --with autotools-dev
debhelper packages
When using debhelper >=9.20160115:
- Call dh_update_autotools_config before running configure
For ealier versions:
- Build-Depend on autotools-dev
- Use dh_autotools-dev_updateconfig in build/configure rule before running configure
- Use dh_autotools-dev_restoreconfig in the clean rule (just before dh_clean)
configure:
dh_autotools-dev_updateconfig
./configure ...
clean:
<package clean commands>
dh_autotools-dev_restoreconfig
dh_clean
CDBS-using packages
- Build-Depend on autotools-dev
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
- Build-Depend on autotools-dev
- Copy in the config.{sub,guess} over any copies in the source. Get the right subdir, and check for multiple subdirs containing copies (this is quite common). They all need to be updated.
configure:
cp -f /usr/share/misc/config.sub .
cp -f /usr/share/misc/config.guess .