25. Automake API versioning

New Automake releases usually include bug fixes and new features. Unfortunately they may also introduce new bugs and incompatibilities. This make four reasons why a package may require a particular Automake version.

Things get worse when maintaining a large tree of packages, each one requiring a different version of Automake. In the past, this meant that any developer (and sometime users) had to install several versions of Automake in different places, and switch `$PATH' appropriately for each package.

Starting with version 1.6, Automake installs versioned binaries. This means you can install several versions of Automake in the same `$prefix', and can select an arbitrary Automake version by running `automake-1.6' or `automake-1.7' without juggling with `$PATH'. Furthermore, `Makefile''s generated by Automake 1.6 will use `automake-1.6' explicitely in their rebuild rules.

Note that `1.6' in `automake-1.6' is Automake's API version, not Automake's version. If a bug fix release is made, for instance Automake 1.6.1, the API version will remain 1.6. This means that a package which work with Automake 1.6 should also work with 1.6.1; after all, this is what people expect from bug fix releases.

Note that if your package relies on a feature or a bug fix introduced in a release, you can pass this version as an option to Automake to ensure older releases will not be used. For instance, use this in your `configure.in':

AM_INIT_AUTOMAKE(1.6.1) dnl Require Automake 1.6.1 or better.

or, in a particular `Makefile.am':

AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.

Automake will print an error message if its version is older than the requested version.

What is in the API

Automake's programing interface is not easy to define. Basically it should include at least all documented variables and targets that a `Makefile.am' authors can use, the behaviours associated to them (e.g. the places where `-hook''s are run), the command line interface of `automake' and `aclocal', ...

What is not in the API

Every undocumented variable, target, or command line option, is not part of the API. You should avoid using them, as they could change from one version to the other (even in bug fix releases, if this helps to fix a bug).

If it turns out you need to use such a undocumented feature, contact [email protected] and try to get it documented and exercised by the test-suite.