automake: API Versioning

1 
1 25 Automake API Versioning
1 **************************
1 
1 New Automake releases usually include bug fixes and new features.
1 Unfortunately they may also introduce new bugs and incompatibilities.
1 This makes four reasons why a package may require a particular Automake
1 version.
1 
1    Things get worse when maintaining a large tree of packages, each one
1 requiring a different version of Automake.  In the past, this meant that
1 any developer (and sometimes users) had to install several versions of
1 Automake in different places, and switch ‘$PATH’ appropriately for each
1 package.
1 
1    Starting with version 1.6, Automake installs versioned binaries.
1 This means you can install several versions of Automake in the same
1 ‘$prefix’, and can select an arbitrary Automake version by running
1 ‘automake-1.6’ or ‘automake-1.7’ without juggling with ‘$PATH’.
1 Furthermore, ‘Makefile’’s generated by Automake 1.6 will use
1 ‘automake-1.6’ explicitly in their rebuild rules.
1 
1    The number ‘1.6’ in ‘automake-1.6’ is Automake’s API version, not
1 Automake’s version.  If a bug fix release is made, for instance Automake
1 1.6.1, the API version will remain 1.6.  This means that a package that
1 works with Automake 1.6 should also work with 1.6.1; after all, this is
1 what people expect from bug fix releases.
1 
1    If your package relies on a feature or a bug fix introduced in a
1 release, you can pass this version as an option to Automake to ensure
1 older releases will not be used.  For instance, use this in your
1 ‘configure.ac’:
1 
1        AM_INIT_AUTOMAKE([1.6.1])    dnl Require Automake 1.6.1 or better.
1 
1 or, in a particular ‘Makefile.am’:
1 
1        AUTOMAKE_OPTIONS = 1.6.1   # Require Automake 1.6.1 or better.
1 
1 Automake will print an error message if its version is older than the
1 requested version.
1 
1 What is in the API
1 ==================
1 
1 Automake’s programming interface is not easy to define.  Basically it
1 should include at least all *documented* variables and targets that a
1 ‘Makefile.am’ author can use, any behavior associated with them (e.g.,
1 the places where ‘-hook’’s are run), the command line interface of
1 ‘automake’ and ‘aclocal’, ...
1 
1 What is not in the API
1 ======================
1 
1 Every undocumented variable, target, or command line option, is not part
1 of the API.  You should avoid using them, as they could change from one
1 version to the other (even in bug fix releases, if this helps to fix a
1 bug).
1 
1    If it turns out you need to use such an undocumented feature, contact
1 <automake@gnu.org> and try to get it documented and exercised by the
1 test-suite.
1