automake-1.16: API Versioning
24 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 sometimes 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.
The number ‘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 that
works with Automake 1.6 should also work with 1.6.1; after all, this is
what people expect from bug fix releases.
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.ac’:
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 an undocumented feature, contact
<automake@gnu.org> and try to get it documented and exercised by the
test-suite.
Info Catalog
automake-1.16: Distributing
automake-1.16: Top
automake-1.16: Upgrading