[OpenBSD]

Porters handbook: autoconf

Autoconf is a gnu tool that is supposed to help in writing portable programs. It is often used together with automake (portable makefiles) and libtool (portable shared libraries).

Those tools do not work all that well, and often set specific challenges in porting software to OpenBSD.

Detecting the use of autoconf in a piece of software

Quite a few software projects have configure scripts, and in most cases, those scripts were generated by autoconf. Such scripts have a line near the top that says: 
# Generated automatically using autoconf version 2.13
or something similar. The generation procedure is covered in a following section. Most often, autoconf ports come with the generated scripts, and with the source scripts that generated these. The next section covers the simple case where you simply want to run the generated script, and not modify it. Make sure you read the section about Trojan horses as well.

Running an autoconf configure script

This script is normally run during the configure stage of ports building. To invoke the configure script, one only has to set CONFIGURE_STYLE= gnu which will automatically invoke ${WRKSRC}/configure.

If your configure script lies elsewhere, just set CONFIGURE_SCRIPT to the right value.

Configure scripts often take a lot of arguments. The default processing of the ports tree will only pass --prefix and --sysconfdir to these. Very old configure scripts don't understand --sysconfdir; you can set CONFIGURE_STYLE=gnu old in such cases.

Similarly, some ports are not aware of DESTDIR. Those ports will often accept setting prefix=${DESTDIR}/usr/local without any issue, which can be done with CONFIGURE_STYLE=gnu dest.

Ports using autoconf and automake will have Makefiles with a specific format, that begins with a few standard locations: If the configure script does not allow you to override these, you may still be able to do it later on during the build or fake stage. This does assume, of course, that the only reference to such a directory is within the generated Makefile.

For instance, a neat trick involves switching sysconfdir to ${LOCALBASE}/share/example/pkgname during the fake stage, to get default config files to package (since packages don't normally store stuff under /etc).

Ports fully using autoconf and automake may support building under a different directory: try setting SEPARATE_BUILD=flavored and see if that works. This would allow you to wipe the build tree without wiping the source tree, by giving you separate ${WRKSRC} and ${WRKBUILD} locations. In a few cases, separate builds may need to use gmake, where the rest of the port is happy with bsd-make, in which case this is not worth it.

automake will generate a few rules to rebuild all the generated scripts if anything changes. These often get in the way of OpenBSD specific patches. For that reason, as soon as CONFIGURE_STYLE corresponds to autoconf use, post-patch will touch various files in a specific order, so that no automake dependencies get triggered later. The list of dependencies is given in tsort(1) order in a file mentioned in REORDER_DEPENDENCIES (the default is ${PORTSDIR}/infrastructure/mk/automake.dep).

The mechanics of configure checks

The configure script first runs a fixed script called config.guess, that will determine which system configure is running on. config.guess does not vary from port to port and is a fixed script, so the OpenBSD ports tree replaces it with a fixed version that knows about some specific OpenBSD architectures. Since most software packages come with bundled config.guess, and since some of them are quite old, this is a necessary step. If a software package contains more than one config.guess, you can overwrite them all by setting MODGNU_CONFIG_GUESS_DIRS to the full list of directories to process.

The configure script generated by autoconf then simply checks all functionality on the existing system, by looking for a compiler, and running simple test programs through it. Since some of these tests are quite lengthy, the ports tree primes configure with a CONFIG_SITE=config.site file. configure will look at the contents of that file first before running the tests. A few configure scripts may have bugs that will prevent them from running correctly in the presence of config.site. Setting CONFIG_SITE to empty will weed out these kind of problems.

Most configure will auto-detect quite a few conditions. It is very important to look at configure's options, at configure's output, and at the generated config.log file: these will tell you what options were found, and what options were not found. This will allow you to find out when configure did not find a package that was installed.

This will also tell you which optional packages configure would find. In the ports tree, those are called hidden dependencies. This is a bad thing: a hidden dependency is some extra package configure will pick up if it's installed. Then it will proceed in building a mutant package. In some cases, the build will fail because of OpenBSD peculiarities. In some cases, the package creation will fail, as some files will have different names. In some cases, the resulting package will be incorrect, as it will fail to record any dependency on the optional package. So looking at configure's output is one of the most important duty of ports' maintainers. Watch out for cascading tests: detecting a given feature may lead a configure script to try out and find some dependent feature, so you will not see the second feature in the configure output unless the first feature is triggered.

In case some hidden dependencies are found, some action should be taken. The most simple action is to install the optional package, and see what configure will do. If it detects the package, one can either disable the detection (by using configure options, or environment variables, or patching the configure script), or verify that the build goes well and add the dependency to the list of dependent packages. A better choice is to figure out a reasonable set of default dependencies, and then add some flavors to cover other common features.

Re-generating configure scripts

Configure scripts are normally generated from a configure.in file (recent versions of autoconf use a configure.ac file instead). A standard library of definitions is often available in an aclocal.m4.

In most cases, patching configure directly is a bad idea. It is better to patch the configure.in file and get the ports tree to call autoconf. Good porters will endeavor to write configure.in changes that they can feed to software authors.

Different versions of autoconf will produce distinct configure scripts. autoconf-2.13 is special: it was used over a fairly long period, and there has been mutant versions of autoconf-2.13 (actually, betas of a newer autoconf) in wide use. Hence, using autoconf-2.13 will often not produce the exact same configure script.

Since having several autoconf versions around at the same time is useful, the autoconf script actually available in the ports tree is part of a port called metaauto. Which autoconf script actually gets called is controlled through the environment variable AUTOCONF_VERSION. Calling autoconf happens if you set CONFIGURE_STYLE=autoconf, together with setting AUTOCONF_VERSION. Versions currently available are 2.13, 2.52, 2.54, 2.56, 2.57, 2.58, 2.59, 2.60, 2.61 and 2.62. These cover 99% of all configure scripts out there.

autoconf relies on the standard unix preprocessor m4(1). Normally, autoconf relies on some features on the GNU version of m4, gm4. Fortunately, OpenBSD's m4 has enough features to run autoconf as well, it just needs to be invoked with -g to handle autoconf. Very seldom, autoconf run with OpenBSD's m4 will produce bogus configure scripts. The OpenBSD developers will fix such an issue.

Trojan horses

Configure scripts are big generated files. They are an ideal hiding place for Trojan horses, and this has indeed already happened in the past. This is the main reason for having most versions of autoconf in the tree: a good porter is expected to check that a generated configure script matches what the ports tree autoconf builds.

Interaction with other programs

autoheader is another program related to autoconf that is normally run to create a config.h.in file. Setting CONFIGURE_STYLE=autoconf will also run autoheader. A few ports don't use autoheader. Setting CONFIGURE_STYLE=autoconf no-autoheader will fix that issue.

libtool has a few specific hooks in configure.in. There is often a libtool.m4 script that goes with it. Getting libtool to do the right thing goes beyond the scope of this documentation.

KDE uses an extra layer on top of autoconf. This extra layer assembles a configure.in file from a set of configure.in.in files, and is also able to tweak both configure.in for snappier results, and Makefile.in to allow for some supplementary options in building, and to automatically insert DESTDIR in the right places. The AUTOCONF variable can be used to tweak the actual autoconf script that gets run, and KDE expects /bin/sh ${WRKDIST}/admin/cvs.sh to work correctly.
OpenBSD www@openbsd.org
$OpenBSD: autoconf.html,v 1.6 2009/01/30 22:25:57 sthen Exp $