automake.info: API versioning

Go forward to Macro and Variable Index
Go backward to Distributing
Go up to Top
Go to the top op automake

Automake API versioning

   New Automake releases usually include bug fixes and new features.
Unfortunately they may also introduce new bugs and incompatibilities.
This makes 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' explicitly 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 programming interface is not easy to define.  Basically it
should include at least all *documented* variables and targets that a
`Makefile.am' author can use, any behavior associated with 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
<automake@gnu.org> and try to get it documented and exercised by the
test-suite.