@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
* 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
* 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
@code{YFLAGS} is @code{AM_YFLAGS}.
-@node Auxiliary Programs, , User Variables, Generalities
+@node Auxiliary Programs, , User Variables, Generalities
@section Programs automake might require
@cindex Programs, auxiliary
* 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
* 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
@cindex Dependency tracking, disabling
-@node EXEEXT, , Dependencies, Programs
+@node EXEEXT, , Dependencies, Programs
@section Support for executable extensions
@cindex Executable extension
@code{SUFFIXES} go at the start of the generated suffixes list, followed
by Automake generated suffixes not already in the list.
-@node Multilibs, , Suffixes, Miscellaneous
+@node Multilibs, , Suffixes, Miscellaneous
@section Support for Multilibs
Automake has support for an obscure feature called multilibs. A
@example
install-data-local:
- $(INSTALL_DATA) $(srcdir)/afile /etc/afile
+ $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
@end example
@cindex -hook targets
@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
-
-@node Distributing, Macro and Variable Index, Extending, Top
+@node Distributing, API versioning, Extending, Top
@chapter Distributing @file{Makefile.in}s
Automake places no restrictions on the distribution of the resulting
package, regardless of the licensing you choose.
+@node API versioning, Macro and Variable Index, Distributing, Top
+@chapter 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
+@samp{$prefix}, and can select an arbitrary Automake version by running
+@samp{automake-1.6} or @samp{automake-1.7} without juggling with
+@samp{$PATH}. 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
+@file{configure.in}:
+
+@example
+ AM_INIT_AUTOMAKE(1.6.1) dnl Require Automake 1.6.1 or better.
+@end example
+@noindent
+or, in a particular @file{Makefile.am}:
+
+@example
+ AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
+@end example
+@noindent
+Automake will print an error message if its version is
+older than the requested version.
+
+
+@heading 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}, ...
+
+@heading 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{automake@@gnu.org} and try to get it documented and exercised by
+the test-suite.
+
@page
-@node Macro and Variable Index, General Index, Distributing, Top
+@node Macro and Variable Index, General Index, API versioning, Top
@unnumbered Macro and Variable Index
@printindex vr
projects / thirdparty / automake.git / commitdiff
