warnings: be less forceful about a missing subdir-objects option.

This change somewhat ameliorates https://bugs.gnu.org/20699.

* bin/automake.in (handle_single_transform): change
forward-incompatibility message for subdir-objects to be
less draconian and less certain that the change will ever be made.
* t/subobj.sh: message text has changed.
* doc/automake.texi (Program and Library Variables): mention
the unfortunate fact that one directory can clean in a sibling,
subdir-objects notwithstanding.

3 files changed, 23 insertions, 11 deletions

diff --git a/bin/automake.in b/bin/automake.in
index ce06437db..96e8c634c 100644
--- a/bin/automake.in
+++ b/bin/automake.in
@@ -1839,22 +1839,27 @@ sub handle_single_transform
                 {
                   # Since the next major version of automake (2.0) will
                   # make the behaviour so far only activated with the
-                  # 'subdir-object' option mandatory, it's better if we
+                  # 'subdir-objects' option mandatory, it's better if we
                   # start warning users not using that option.
                   # As suggested by Peter Johansson, we strive to avoid
                   # the warning when it would be irrelevant, i.e., if
                   # all source files sit in "current" directory.
+                  #
+                  # There are problems with making this change; see
+                  # https://bugs.gnu.org/20699 before making
+                  # subdir-objects, let alone unconditional.
+                  # (Making it non-overridable seems especially wrong.)
+                  #
                   msg_var 'unsupported', $var,
                           "source file '$full' is in a subdirectory,"
                           . "\nbut option 'subdir-objects' is disabled";
                   msg 'unsupported', INTERNAL, <<'EOF', uniq_scope => US_GLOBAL;
 possible forward-incompatibility.
-At least a source file is in a subdirectory, but the 'subdir-objects'
+At least one source file is in a subdirectory, but the 'subdir-objects'
 automake option hasn't been enabled.  For now, the corresponding output
-object file(s) will be placed in the top-level directory.  However,
-this behaviour will change in future Automake versions: they will
-unconditionally cause object files to be placed in the same subdirectory
-of the corresponding sources.
+object file(s) will be placed in the top-level directory.  However, this
+behavior may change in a future Automake major version, with object
+files being placed in the same subdirectory as the corresponding sources.
 You are advised to start using 'subdir-objects' option throughout your
 project, to avoid future incompatibilities.
 EOF
diff --git a/doc/automake.texi b/doc/automake.texi
index 390b4ffd2..7e0ad1b05 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -5758,18 +5758,25 @@ be put into the current build directory.  However, if the option
 @file{.o} file will be put into the subdirectory named after the
 source file.  For instance, with @option{subdir-objects} enabled,
 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}.  Some
-people prefer this mode of operation.  You can specify
+projects prefer or require this mode of operation.  You can specify
 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
 @cindex Subdirectory, objects in
 @cindex Objects in subdirectory
 
+@c https://bugs.gnu.org/20699
+When @option{subdir-objects} is specified, and source files which lie
+outside the current directory tree are nevertheless specified, as in
+@code{foo_SOURCES = ../lib/other.c}, Automake will still remove
+@file{../lib/other.o}, in fact, @file{../lib/*.o} (e.g., at @code{make
+clean}, even though it is arguably wrong for one subdirectory to
+clean in a sibling.  This may or may not be changed in the future.
 
 @item EXTRA_maude_SOURCES
 Automake needs to know the list of files you intend to compile
 @emph{statically}.  For one thing, this is the only way Automake has of
 knowing what sort of language support a given @file{Makefile.in}
-requires.  @footnote{There are other, more obscure reasons for
-this limitation as well.}  This means that, for example, you can't put a
+requires.  (There are other, more obscure reasons for
+this limitation as well.)  This means that, for example, you can't put a
 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
 variable.  If you intend to conditionally compile source files and use
 @file{configure} to substitute the appropriate object names into, e.g.,
@@ -10483,7 +10490,7 @@ If this option is specified, then objects are placed into the
 subdirectory of the build directory corresponding to the subdirectory of
 the source file.  For instance, if the source file is
 @file{subdir/file.cxx}, then the output file would be
-@file{subdir/file.o}.
+@file{subdir/file.o}.  @xref{Program and Library Variables}.
 
 @anchor{tar-formats}
 @item @option{tar-v7}
diff --git a/t/subobj.sh b/t/subobj.sh
index b958fc68e..1654ddcba 100644
--- a/t/subobj.sh
+++ b/t/subobj.sh
@@ -50,8 +50,8 @@ grep "option 'subdir-objects' is disabled" stderr
 # Verbose tips should be given, but not too many times.
 for msg in \
   "possible forward-incompatibility" \
+  "For now,.* corresponding" \
   "advi[sc]e.* 'subdir-objects' option throughout" \
-  "unconditionally.* object file.* same subdirectory" \
 ; do
   test $(grep -c "$msg" stderr) -eq 1
 done