From: Stefano Lattarini Date: Sat, 31 Mar 2012 09:04:41 +0000 (+0200) Subject: docs: deprecate 'cygnus' mode, help the transition X-Git-Tag: v1.11.4~1^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d714ec513745fe50c03d49c9ab6481ce36d3a27e;p=thirdparty%2Fautomake.git 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 --- diff --git a/THANKS b/THANKS index 702c97bda..a2091ab3c 100644 --- a/THANKS +++ b/THANKS @@ -178,6 +178,7 @@ John Ratliff autoconf@technoplaza.net John R. Cary cary@txcorp.com John W. Coomes jcoomes@eng.Sun.COM Jonathan Nieder jrnieder@gmail.com +Joseph S. Myers joseph@codesourcery.com Josh MacDonald jmacd@cs.berkeley.edu Joshua Cowan jcowan@jcowan.reslife.okstate.edu js pendry js.pendry@msdw.com diff --git a/doc/automake.texi b/doc/automake.texi index 9b6b8f54e..3389f8a74 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). -@xref{Cygnus}, 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. +@emph{The 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 @@ -10335,45 +10345,40 @@ comply with Cygnus rules. 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. @item -@file{texinfo.tex} 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. +The @option{foreign} strictness is implied. @item -@samp{make 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 +@option{no-dist} 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}, -@command{makeinfo} and @command{texi2dvi}. +The macro @code{AM_MAINTAINER_MODE} is required. @item -@option{--foreign} 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. +@file{texinfo.tex} 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}, +@command{makeinfo} 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