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
.PHONYautotools
(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 <hmh@debian.org>