RFC: documentation for API

[Alexandre Duret-Lutz]

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
<address@hidden> and try to get it documented and exercised by the
test-suite.


2002-01-29  Alexandre Duret-Lutz  <address@hidden>

        * automake.texi (API versioning): New Node.
        (Extending): Use $(DESTDIR) in examples.

Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.262
diff -u -r1.262 automake.texi
--- automake.texi       2002/01/24 08:17:35     1.262
+++ automake.texi       2002/01/29 11:32:46
@@ -20,7 +20,7 @@
 @ifinfo
 This file documents GNU automake @value{VERSION}
 
-Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001
+Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002
 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
@@ -133,6 +133,7 @@
 * Cygnus::                      The effect of @code{--cygnus}
 * Extending::                   Extending Automake
 * Distributing::                Distributing the Makefile.in
+* API versioning::              About compatibility between Automake versions
 * Macro and Variable Index::
 * General Index::
 @end menu
@@ -200,7 +201,7 @@
 * Strictness::                  Standards conformance checking
 * Uniform::                     The Uniform Naming Scheme
 * Canonicalization::            How derived variables are named
-* User Variables::             Variables reserved for the user
+* User Variables::              Variables reserved for the user
 * Auxiliary Programs::          Programs automake might require
 @end menu
 
@@ -524,7 +525,7 @@
 @code{YFLAGS} is @code{AM_YFLAGS}.
 
 
address@hidden Auxiliary Programs, , User Variables, Generalities
address@hidden Auxiliary Programs,  , User Variables, Generalities
 @section Programs automake might require
 
 @cindex Programs, auxiliary
@@ -1654,8 +1655,7 @@
 * A Program::                   Building a program
 * A Library::                   Building a library
 * A Shared Library::            Building a Libtool library
-* Program and Library Variables::
-                               Variables controlling program and
+* Program and Library Variables::  Variables controlling program and
                                 library builds
 * LIBOBJS::                     Special handling for LIBOBJS and ALLOCA
 * Program variables::           Variables used when building a program
@@ -1667,7 +1667,7 @@
 * Support for Other Languages::
 * ANSI::                        Automatic de-ANSI-fication
 * Dependencies::                Automatic dependency tracking
-* EXEEXT::                     Support for executable extensions
+* EXEEXT::                      Support for executable extensions
 @end menu
 
 
@@ -2814,7 +2814,7 @@
 @cindex Dependency tracking, disabling
 
 
address@hidden EXEEXT, , Dependencies, Programs
address@hidden EXEEXT,  , Dependencies, Programs
 @section Support for executable extensions
 
 @cindex Executable extension
@@ -4124,7 +4124,7 @@
 @code{SUFFIXES} go at the start of the generated suffixes list, followed
 by Automake generated suffixes not already in the list.
 
address@hidden Multilibs, , Suffixes, Miscellaneous
address@hidden Multilibs,  , Suffixes, Miscellaneous
 @section Support for Multilibs
 
 Automake has support for an obscure feature called multilibs.  A
@@ -4424,7 +4424,7 @@
 
 @example
 install-data-local:
-        $(INSTALL_DATA) $(srcdir)/afile /etc/afile
+        $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
 @end example
 
 @cindex -hook targets
@@ -4444,14 +4444,13 @@
 
 @example
 install-exec-hook:
-        ln $(bindir)/program $(bindir)/proglink
+        ln $(DESTDIR)$(bindir)/program $(DESTDIR)$(bindir)/proglink
 @end example
 
 @c FIXME should include discussion of variables you can use in these
 @c rules
 
-
address@hidden Distributing, Macro and Variable Index, Extending, Top
address@hidden Distributing, API versioning, Extending, Top
 @chapter Distributing @file{Makefile.in}s
 
 Automake places no restrictions on the distribution of the resulting
@@ -4465,8 +4464,73 @@
 package, regardless of the licensing you choose.
 
 
address@hidden API versioning, Macro and Variable Index, Distributing, Top
address@hidden 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 @samp{$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
address@hidden, and can select an arbitrary Automake version by running
address@hidden or @samp{automake-1.7} without juggling with
address@hidden  Furthermore, @file{Makefile}'s generated by Automake 1.6
+will use @samp{automake-1.6} explicitely in their rebuild rules.
+
+Note that @samp{1.6} in @samp{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
address@hidden:
+
address@hidden
+  AM_INIT_AUTOMAKE(1.6.1)    dnl Require Automake 1.6.1 or better.
address@hidden example
address@hidden
+or, in a particular @file{Makefile.am}:
+
address@hidden
+  AUTOMAKE_OPTIONS = 1.6.1   # Require Automake 1.6.1 or better.
address@hidden example
address@hidden
+Automake will print an error message if its version is
+older than the requested version.
+
+
address@hidden What is in the API
+
+Automake's programing interface is not easy to define.  Basically it
+should include at least all @strong{documented} variables and targets
+that a @samp{Makefile.am} authors can use, the behaviours associated to
+them (e.g. the places where @samp{-hook}'s are run), the command line
+interface of @samp{automake} and @samp{aclocal}, ...
+
address@hidden 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
address@hidden@@gnu.org} and try to get it documented and exercised by
+the test-suite.
+
 @page
address@hidden Macro and Variable Index, General Index, Distributing, Top
address@hidden Macro and Variable Index, General Index, API versioning, Top
 @unnumbered Macro and Variable Index
 
 @printindex vr

-- 
Alexandre Duret-Lutz