>From 5bb72934aa7d96e2faa90fa1c59c24f01e83c91f Mon Sep 17 00:00:00 2001 Message-Id: From: Stefano Lattarini Date: Sat, 31 Mar 2012 11:04:41 +0200 Subject: [PATCH] docs: deprecate 'cygnus' mode, help the transition Support for "Cygnus-style" trees (so far enabled by the 'cygnus' option) will be deprecated in one release of the next major series (1.12.x) and removed in the next major release after that (1.13). Better to start warning about this in the manual. * docs/automake.texi: Warn about the oncoming deprecation of the 'cygnus' mode. Suggest some idioms that can be used to retain some effects of the 'cygnus' option. * THANKS: Update. >From a suggestion by Joseph S. Myers in automake bug#11034. Signed-off-by: Stefano Lattarini --- THANKS | 1 + doc/automake.texi | 68 ++++++++++++++++++++++++++++------------------------- 2 files changed, 37 insertions(+), 32 deletions(-) diff --git a/THANKS b/THANKS index 702c97b..a2091ab 100644 --- a/THANKS +++ b/THANKS @@ -178,6 +178,7 @@ John Ratliff address@hidden John R. Cary address@hidden John W. Coomes address@hidden Jonathan Nieder address@hidden +Joseph S. Myers address@hidden Josh MacDonald address@hidden Joshua Cowan address@hidden js pendry address@hidden diff --git a/doc/automake.texi b/doc/automake.texi index 9b6b8f5..9da5fd9 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -117,7 +117,7 @@ section entitled ``GNU Free Documentation License.'' * Conditionals:: Conditionals * Silencing Make:: Obtain less verbose output from @command{make} * Gnits:: The effect of @option{--gnu} and @option{--gnits} -* Cygnus:: The effect of @option{--cygnus} +* Cygnus:: The effect of @option{--cygnus} (deprecated, soon to be removed) * Not Enough:: When Automake is not Enough * Distributing:: Distributing the Makefile.in * API Versioning:: About compatibility between Automake versions @@ -1943,10 +1943,13 @@ standard is actually published (which may never happen). @xref{Gnits}, for more information on the precise implications of the strictness level. -Automake also has a special ``cygnus'' mode that is similar to -strictness but handled differently. This mode is useful for packages -that are put into a ``Cygnus'' style tree (e.g., the GCC tree). address@hidden, for more information on this mode. +Automake also has a special (and @emph{today deprecated}) ``cygnus'' mode +that is similar to strictness but handled differently. This mode is +useful for packages that are put into a ``Cygnus'' style tree (e.g., older +versions of the GCC and gdb trees). @xref{Cygnus}, for more information +on this mode. Please note that this mode is deprecated and @emph{will be +removed in the future automake versions}; you must avoid its use in new +packages, and should stop using it in existing packages as well. @node Uniform @@ -2602,6 +2605,8 @@ copied. The default is to make a symbolic link. @opindex --cygnus Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead of GNU or Gnits rules. For more information, see @ref{Cygnus}. +Note that @emph{this mode of operation is deprecated, and will be removed} +in a future Automake release. @item -f @opindex -f @@ -10322,10 +10327,15 @@ The file @file{THANKS} is required. @cindex @option{cygnus} strictness -Some packages, notably GNU GCC and GNU gdb, have a build environment -originally written at Cygnus Support (subsequently renamed Cygnus -Solutions, and then later purchased by Red Hat). Packages with this -ancestry are sometimes referred to as ``Cygnus'' trees. address@hidden features described in this section are deprecated; you must +not use any of them in new code, and should remove their use from older +but still maintained code: they will be withdrawn in a future Automake +release.} + +Some packages, notably GNU GCC and GNU gdb, used to have a build +environment originally written at Cygnus Support (subsequently renamed +Cygnus Solutions, and then later purchased by Red Hat). Packages with +this ancestry are sometimes referred to as ``Cygnus'' trees. A Cygnus tree has slightly different rules for how a @file{Makefile.in} is to be constructed. Passing @option{--cygnus} to @@ -10336,44 +10346,38 @@ Here are the precise effects of @option{--cygnus}: @itemize @bullet @item -Info files are always created in the build directory, and not in the -source directory. - address@hidden address@hidden is not required if a Texinfo source file is -specified. The assumption is that the file will be supplied, but in a -place that Automake cannot find. This assumption is an artifact of how -Cygnus packages are typically bundled. address@hidden is implied. @item address@hidden dist} is not supported, and the rules for it are not -generated. Cygnus-style trees use their own distribution mechanism. +The options @option{no-installinfo}, @option{no-dependencies} and address@hidden are implied (@pxref{Options}). @item -Certain tools will be searched for in the build tree as well as in the -user's @env{PATH}. These tools are @command{runtest}, @command{expect}, address@hidden and @command{texi2dvi}. +The macro @code{AM_MAINTAINER_MODE} is required. @item address@hidden is implied. +Info files are always created in the build directory, and not in the +source directory. Packages that don't use the @option{cygnus} option +can emulate this effect by using the @option{no-installinfo} option +and listing the generated info files in the @code{CLEANFILES} variable. @item -The options @option{no-installinfo} and @option{no-dependencies} are -implied. address@hidden is not required if a Texinfo source file is +specified. The assumption is that the file will be supplied, but in a +place that Automake cannot find -- it is an artifact of how Cygnus +packages are typically bundled. This effect can be emulated in +packages not using the @option{cygnus} option with a proper definition +of the @code{TEXINFO_TEX} variable, @pxref{Texinfo}. @item -The macro @code{AM_MAINTAINER_MODE} is required. +Certain tools will be searched for in the build tree as well as in the +user's @env{PATH}. These tools are @command{runtest}, @command{expect}, address@hidden and @command{texi2dvi}. @item The @code{check} target doesn't depend on @code{all}. @end itemize -GNU maintainers are advised to use @option{gnu} strictness in preference -to the special Cygnus mode. Some day, perhaps, the differences between -Cygnus trees and GNU trees will disappear (for instance, as GCC is made -more standards compliant). At that time the special Cygnus mode will be -removed. - @node Not Enough @chapter When Automake Isn't Enough -- 1.7.9