Subject: bug#11034: Binutils, GDB, GCC and Automake's 'cygnus' option

From: Stefano Lattarini <[email-masked]>
Date: Sat, 31 Mar 2012 13:38:34 +0200

On 03/28/2012 02:19 PM, Stefano Lattarini wrote:
> Hi Joseph, thanks for the feedback.
> On 03/28/2012 01:24 PM, Joseph S. Myers wrote:
>>
>> Is there better transition documentation somewhere?
>>
> Nope, but it would be a good idea to prepare it before starting to deprecate
> the 'cygnus' option.  Maybe even for 1.12.  Thanks for the suggestion.
>
Or even for 1.11.4, which is to be released in two/three days.  What about the
attached patch?  I will push it by this evening if there is no objection.

Thanks,
  Stefano
>From 5bb72934aa7d96e2faa90fa1c59c24f01e83c91f Mon Sep 17 00:00:00 2001
Message-Id: <5bb72934a[email-masked]>
From: Stefano Lattarini <[email-masked]>
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 <[email-masked]>
---
 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		[email-masked]
 John R. Cary		[email-masked]
 John W. Coomes		[email-masked]
 Jonathan Nieder		[email-masked]
+Joseph S. Myers		[email-masked]
 Josh MacDonald		[email-masked]
 Joshua Cowan		[email-masked]
 js pendry		[email-masked]
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).
-@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
@@ -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.
-
-@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.
+@option{--foreign} 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
-- 
1.7.9