autotools-dev for Debian $Id: README.Debian,v 1.13 2002/03/05 00:09:17 hmh Exp $ -------------------------------------------------------- (Before packaging something in Debian that uses gnu autoconf, you must read the "Introduction" and the "Calling GNU configure properly" sections) Introduction: ------------- The config.guess and config.sub files, used by autoconf- and automake- generated scripts, need to be constantly updated to address new architectures. Unfortunately, Debian's automake package has failed to provide such timely updates regularly, and even if it did, most developers are not even aware of the need for such updates. Their upstream often isn't, either. The result ends up as serious bugs filled in the BTS by porters. Given the amount of packages using autoconf and automake in Debian, we are talking about a rather large number of bugs every time we start supporting a new architecture. There is currently no way around an updated config.sub file. Even if one supplies to a GNU autoconf (configure) script the build and target hosts, config.sub is needed to get the canonical GNU hostname. In fact, an outdated config.sub script in that case might break any new architecture in Debian just the same. This package gives you tools to fix this problem, as well as some of the accumulated knowledge I (and others) got from dealing with the GNU autotools and their effect on CVS, upstream and Debian auto-builders. Please read this file throughoutly before you package something that uses GNU config/autoconf. Calling GNU configure properly: ------------------------------- You should not[1] simply call ./configure with the proper prefix and package- dependent options and be done with it (regardless of the fact that just about all Debian packages do so, including some of mine until their next upload :P). [1] As in: it is a bug if you do so, see Debian policy 2.4.3 and 5.2. UNLESS you know better, and your package has very specific needs (hint: you build several subarch variants, such as with MMX, i586-optimized, i686-optimized... binary packages AND you use the config.guess output to detect your build target), you should call configure this way (for autoconf 2.52): export DEB_HOST_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_HOST_GNU_TYPE) export DEB_BUILD_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_BUILD_GNU_TYPE) # FOR AUTOCONF 2.52 AND NEWER ONLY ifeq ($(DEB_BUILD_GNU_TYPE), $(DEB_HOST_GNU_TYPE)) confflags += --build $(DEB_HOST_GNU_TYPE) else confflags += --build $(DEB_BUILD_GNU_TYPE) --host $(DEB_HOST_GNU_TYPE) endif ./configure $(confflags) \ ....... (other configure options) ...... This will tell configure to build for the proper architecture, even if you do not use dpkg-buildpackage, or manually override DEB_HOST_GNU_TYPE and DEB_BUILD_GNU_TYPE for cross-compiling. It requires GNU make and dpkg-dev, but those packages are build-essential in Debian, so that should not be a problem. YOU STILL NEED AN UP-TO-DATE config.sub FILE TO AVOID BREAKAGE IN NEW ARCHITECTURES, EVEN WITH THIS SETUP. BTW, autoconf 2.52+ should enter crosscompiling mode if --host is specified. It will build in crosscompiling mode even if build and host type are the same (this information comes directly from autoconf upstream). One could remove (or fail to update) config.guess when using the above setup, since it is usually not called by configure anymore. I prefer to keep both files updated and in place just in case, and for completeness. For packages that use the outdated autoconf 2.13, one might need to use the following makefile snippet, to work around the bad semantics for --build and --host in 2.13: # FOR AUTOCONF 2.13 ONLY ifeq ($(DEB_BUILD_GNU_TYPE), $(DEB_HOST_GNU_TYPE)) confflags += $(DEB_HOST_GNU_TYPE) else confflags += --host $(DEB_BUILD_GNU_TYPE) --build $(DEB_HOST_GNU_TYPE) endif It is very easy to know which version of autoconf was used to build a configure script. Just use "head configure" and read the comments. The outdated GNU config.{sub,guess} problem and solutions: ---------------------------------------------------------- GNU autotools need the config.sub (and sometimes config.guess) file when the AC_CANONICAL_HOST, AC_CANONICAL_SYSTEM macros are used, and also when libtool is in use. It might need them in other circunstances, so don't hold your breath. An out-of-date config.sub will break builds in any architecture it doesn't know about. The same goes for config.guess, if it is used (so, don't use it). To fix this particular problem automatically, we need both a source of fresh copies for config.{sub,guess} in Debian, as well as a way to get them inside the packages during their build. autotools-dev provides the fresh copies of config.{sub,guess} for any programs that might need them (in /usr/share/misc), including automake and libtool. By inserting some code in the debian/rules file (the clean target is the best place for this, as it guarantees the updated files will make it to the source package when dpkg-buildpackage is run), the whole process can be safely automated: The config.guess and config.sub files will be updated at every build, then. Just add: -test -r /usr/share/misc/config.sub && \ cp -f /usr/share/misc/config.sub config.sub -test -r /usr/share/misc/config.guess && \ cp -f /usr/share/misc/config.guess config.guess to the clean target of debian/rules. Or, if you are so inclined, replace config.sub and config.guess with symlinks to the /usr/share/misc/ copies in the build target. This requires a build-time dependency on autotools-dev. Also, if you dislike not being able to know when a auto-builder did an update before you could, and didn't let you know that it uploaded files built against newer config.sub/.guess than your source package (which, I should add, causes no difference in the build result for supported archs, just allows for new archs to be built): clean: autotools [other dependencies] [clean target] # The autotools target adds forced build-time dependencies on # autotools-dev (for /usr/share/misc/config.*) and devscripts (for dch) # It's also a .PHONY make target. autotools: OLDDATESUB=`./config.sub -t | tr -d -` ;\ OLDDATEGUESS=`./config.guess -t | tr -d -` ;\ NEWDATESUB=`/usr/share/misc/config.sub -t | tr -d -` ;\ NEWDATEGUESS=`/usr/share/misc/config.guess -t | tr -d -` ;\ if [ $$OLDDATESUB -lt $$NEWDATESUB -o \ $$OLDDATEGUESS -lt $$NEWDATEGUESS ]; then \ dch -a -p "GNU config automated update: config.sub\ ($$OLDDATESUB to $$NEWDATESUB), config.guess\ ($$OLDDATEGUESS to $$NEWDATEGUESS)" ;\ cp -f /usr/share/misc/config.sub config.sub ;\ cp -f /usr/share/misc/config.guess config.guess ;\ echo WARNING: GNU config scripts updated from master copies 1>&2 ;\ fi .PHONY autotools (do not forget the build-depends!. The above script will FAIL if the config.sub in the package is so old it doesn't support -t. Do the first upgrade by hand -- such ancient config.sub/guess scripts are NOT allowed in Debian, they break a lot of our ports and are considered Release Critical bugs). You could also use something like automake --force, to update those files. However, that will cause severe headaches if automake has been through one of its not-fully-backwards-compatible updates... Packages that can take advantage of autotools-dev at build time should Build-Depend on it. Packages that do such work in a script that is run before the source package is built (see autogen.sh, described elsewhere in this text) will need not such a build-dependency (but please document the packages your autogen.sh-like script needs in comments at the top of that file!). The problem with timestamp skews and Debian source packages: ------------------------------------------------------------ As of the time this document is being written, dpkg-source cannot automatically fix the severe timestamp skew problems that applying a diff file over a tarball-extracted tree generate. The result of these timestamp skew problems is that most programs that use autoconf and automake will often try to regenerate their configure and Makefiles. (Note: dpkg-source from the dpkg version 1.10 solves this problem, but it will only be available in sarge and sid, not woody) It is very likely that the autoconf, automake and all related libraries your package might need will NOT be exactly the same in the auto-builder/end-user build environment and yours. This IS guaranteed to cause severe headaches. And it wastes CPU time in auto-builders, too. Do recall that some architectures are very slow (m68k, for example), and that any wastage of auto-build time is a severe problem for Debian as a whole (it delays packages from moving to Debian testing, for one!). Users of automake can use of AM_MAINTAINER_MODE in configure.{ac,in}, as that will tell automake to generate Makefiles that do not try to rebuild the configure files by default. Ask upstream to use it too, it is better for the normal users. One can fix the timestamp skews using a proper chain of "touch foo && touch bar..." in the debian/rules file, to make sure files will not be regenerated without need. Due to what I perceive as a design failure in current dpkg-source (we do not have a "you must run this target to proper cleanup the tree before the first build" target), one must choose either the clean target, or a target that gets called by the "binary-indep" or "binary-arch" targets BEFORE the package's makefile/configure script is run and has a chance to act on the bad timestamps. My personal choice is to run the following just before calling configure: touch configure.in && \ touch aclocal.m4 && \ touch configure (note that the package I got that example from, fetchmail, does not use automake). Proper ordering of the touch commands is extremely important, so you must enforce it using the '&&'. Get it wrong, and you will break the build. Miss one file you need to touch, and you will have a lurking problem waiting to spring on you. When in doubt, you can clean the build tree and touch every file TO THE SAME TIMESTAMP (hint: use touch -r). GNU config, autoconf/automake/autoheader, libtool, gettext and CVS: ------------------------------------------------------------------- This text applies to any machine-generated build-time files, such as those one gets when one runs gettextize, libtoolize, autoconf, automake, autoheader, aclocal, bison... Experience shows that such files must NOT be kept on CVS. As one prominent Debian developer so kindly put in IRC, when I first asked about the problem: "If you do something like that [keep gettext in your CVS tree] you are weird. Go away." It took me no time flat to understand the wisdom of his words, and my local fetchmail repository was properly clean of all gettext, autoconf and other machine-generated files by the next morning. Why? Because such files are supposed to be regenerated at every build, from up-to-date, fresh copies of their master files. "But upstream keeps such stuff in his CVS/tar/whatever repository!". Well, duh. Your upstream probably doesn't know better. I know for a fact my upstream didn't, either. And if such files are auto-generated properly at every new maintainer build, the outdated config.{sub,guess} (as well as the outdated gettext, outdated libtool, outdated automake...) problem is severely mitigated. And it will help the auto-builders, too. Your .diff file WILL grow, often a lot. But this is the best compromise, really. We do not want whatever possibly broken crap upstream has for gettext, autoconf and friends screwing up Debian automated builds. The gettext, libtool and autoconf Debian maintainers take great pain to make sure their packages are up-to-date, bug-free and work sanely on all Debian-supported architectures. All that work goes down the drain if you leave some old config.sub from an unknown variant of some weird distribution of 3 years ago just because your upstream happens to like it. Debian's cvs-buildpackage properly supports generating all the autoconf/ gettext/whatever stuff on CVS export time (cvs-buildpackage will build the package from a clean, recently exported tree; not from your working repository). The usual way to do this is to create an autogen.sh script, that one runs to get it to call aclocal, autoheader, autoconf, automake, libtoolize, gettextize in the proper order, and with the proper parameters. This is the solution adopted by may clueful upstream projects, as well (although the name of the autogen.sh script varies). One can either get this script to be run by configuring CVS to do so, or by adding some Makefile rules in debian/rules. Do note that a properly done autogen.sh invocation runs before dpkg has a chance to build the source package, so as to make sure an user does NOT need any of the programs called by autogen.sh to build the package. This will, in fact, ease the load on auto-builders as well since the program will build much faster. DO pay attention to the timestamp skew problem discussed somewhere else in this file, though. Also, here's a free hint: adding the automatic-generated files to .cvsignore files, and adding the .cvsignore files to the CVS tree will ease the usage of CVS a lot when a new upstream version arrives. Sample autogen.sh and debian/rules files can be found in /usr/share/doc/autotools-dev/examples. Do not use them. Rather, properly customize your own. -- Henrique de Moraes Holschuh