From a6ef8de131bf4234dbb14bfe63dabb11c4aca684 Mon Sep 17 00:00:00 2001 From: Alexandre Duret-Lutz Date: Wed, 30 Jan 2002 08:05:36 +0000 Subject: [PATCH] * automake.texi (API versioning): New Node. (Extending): Use $(DESTDIR) in examples. --- ChangeLog | 5 +++ automake.texi | 90 +++++++++++++++++++++++++++++++++++++++++++-------- stamp-vti | 2 +- version.texi | 2 +- 4 files changed, 84 insertions(+), 15 deletions(-) diff --git a/ChangeLog b/ChangeLog index 7e2dfd78..312c8447 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2002-01-30 Alexandre Duret-Lutz + + * automake.texi (API versioning): New Node. + (Extending): Use $(DESTDIR) in examples. + 2002-01-28 Akim Demaille * m4/lispdir.m4 (AM_PATH_LISPDIR): Serial 5. diff --git a/automake.texi b/automake.texi index 572ef498..61105de6 100644 --- a/automake.texi +++ b/automake.texi @@ -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 @@ This edition documents version @value{VERSION}. * 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 @@ understand how Automake works. * 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 @@ user variable's name. For instance, the shadow variable for @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 @@ -1654,8 +1655,7 @@ to build programs and libraries. * 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 @@ to build programs and libraries. * 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 @@ tracking by configuring with @code{--disable-dependency-tracking}. @cindex Dependency tracking, disabling -@node EXEEXT, , Dependencies, Programs +@node EXEEXT, , Dependencies, Programs @section Support for executable extensions @cindex Executable extension @@ -4124,7 +4124,7 @@ Automake generate the suffix list for @code{.SUFFIXES}. Any given @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 @@ -4424,7 +4424,7 @@ For instance, here is one way to install a file in @file{/etc}: @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 @@ For instance, here is how to create a hard link to an installed program: @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 @@ -4465,8 +4464,73 @@ have a special exception allowing you to distribute them with your 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 diff --git a/stamp-vti b/stamp-vti index c89d366c..78b25572 100644 --- a/stamp-vti +++ b/stamp-vti @@ -1,4 +1,4 @@ -@set UPDATED 27 January 2002 +@set UPDATED 30 January 2002 @set UPDATED-MONTH January 2002 @set EDITION 1.5e @set VERSION 1.5e diff --git a/version.texi b/version.texi index c89d366c..78b25572 100644 --- a/version.texi +++ b/version.texi @@ -1,4 +1,4 @@ -@set UPDATED 27 January 2002 +@set UPDATED 30 January 2002 @set UPDATED-MONTH January 2002 @set EDITION 1.5e @set VERSION 1.5e -- 2.43.5