Issue 2231: Add a --warn=future-deprecated option, along with

FutureDeprecatedWarning and MandatoryDeprecatedWarning subclasses.
Use these to future-deprecate the Taskmaster.Task class, which we intend
to turn into an abstract base class by requiring subclasses to implement
the .needs_execute() method.

6 files changed, 111 insertions, 4 deletions

diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 123ca5c..300e14c 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -1352,8 +1352,16 @@ These warnings are disabled by default.
 
 .TP
 --warn=deprecated, --warn=no-deprecated
-Enables or disables all warnings about use of deprecated features.
+Enables or disables all warnings about use of
+currently deprecated features.
 These warnings are enabled by default.
+Note that the
+.b --warn=no-deprecated
+option does not disable warnings about absolutely all deprecated features.
+Warnings for some deprecated features that have already been through
+several releases with deprecation warnings
+may be mandatory for a release or two
+before they are officially no longer supported by SCons.
 Warnings for some specific deprecated features
 may be enabled or disabled individually;
 see below.
@@ -1396,6 +1404,18 @@ Fortran and C++ object files in a single executable,
 which can yield unpredictable behavior with some compilers.
 
 .TP
+--warn=future-deprecated, --warn=no-future-deprecated
+Enables or disables warnings about features
+that will be deprecated in the future.
+These warnings are disabled by default.
+Enabling this warning is especially
+recommended for projects that redistribute
+SCons configurations for other users to build,
+so that the project can be warned as soon as possible
+about to-be-deprecated features
+that may require changes to the configuration.
+
+.TP
 --warn=link, --warn=no-link
 Enables or disables warnings about link steps.
 
diff --git a/src/CHANGES.txt b/src/CHANGES.txt
index 8fca663..75b0401 100644
--- a/src/CHANGES.txt
+++ b/src/CHANGES.txt
@@ -15,6 +15,9 @@ RELEASE 1.X - XXX
     - Print the message, "scons: Build interrupted." on error output,
       not standard output.
 
+    - Add a --warn=future-deprecated option for advance warnings about
+      deprecated features that still have warnings hidden by default.
+
   From Matthew Wesley:
 
     - Copy file attributes so we identify, and can link a shared library
diff --git a/src/engine/SCons/Taskmaster.py b/src/engine/SCons/Taskmaster.py
index f360402..934e28b 100644
--- a/src/engine/SCons/Taskmaster.py
+++ b/src/engine/SCons/Taskmaster.py
@@ -58,6 +58,7 @@ import traceback
 
 import SCons.Errors
 import SCons.Node
+import SCons.Warnings
 
 StateString = SCons.Node.StateString
 NODE_NO_STATE = SCons.Node.no_state
@@ -202,6 +203,9 @@ class Task:
         # Deprecation Cycle) so the desired behavior is explicitly
         # determined by which concrete subclass is used.
         #raise NotImplementedError
+        msg = ('Direct use of the Taskmaster.Task class will be deprecated\n'
+               + '\tin a future release.')
+        SCons.Warnings.warn(SCons.Warnings.TaskmasterNeedsExecuteWarning, msg)
         return True
 
     def execute(self):
diff --git a/src/engine/SCons/Warnings.py b/src/engine/SCons/Warnings.py
index 03ab9ae..83e3ccb 100644
--- a/src/engine/SCons/Warnings.py
+++ b/src/engine/SCons/Warnings.py
@@ -37,6 +37,21 @@ import SCons.Errors
 class Warning(SCons.Errors.UserError):
     pass
 
+class MandatoryWarning(Warning):
+    pass
+
+
+
+class FutureDeprecatedWarning(Warning):
+    pass
+
+class DeprecatedWarning(Warning):
+    pass
+
+class MandatoryDeprecatedWarning(MandatoryWarning):
+    pass
+
+
 
 # NOTE:  If you add a new warning class, add it to the man page, too!
 
@@ -49,9 +64,6 @@ class CorruptSConsignWarning(Warning):
 class DependencyWarning(Warning):
     pass
 
-class DeprecatedWarning(Warning):
-    pass
-
 class DeprecatedCopyWarning(DeprecatedWarning):
     pass
 
@@ -97,6 +109,9 @@ class ReservedVariableWarning(Warning):
 class StackSizeWarning(Warning):
     pass
 
+class TaskmasterNeedsExecuteWarning(FutureDeprecatedWarning):
+    pass
+
 class FortranCxxMixWarning(LinkWarning):
     pass
 
@@ -186,5 +201,8 @@ def process_warn_strings(arguments):
         else:
             if enable:
                 enableWarningClass(clazz)
+            elif issubclass(clazz, MandatoryDeprecatedWarning):
+                fmt = "Can not disable mandataory warning: '%s'\n"
+                sys.stderr.write(fmt % arg)
             else:
                 suppressWarningClass(clazz)
diff --git a/src/engine/SCons/WarningsTests.py b/src/engine/SCons/WarningsTests.py
index 0964699..228c82c 100644
--- a/src/engine/SCons/WarningsTests.py
+++ b/src/engine/SCons/WarningsTests.py
@@ -94,6 +94,10 @@ class WarningsTestCase(unittest.TestCase):
                             "Foo")
         assert to.out is None, to.out
 
+        SCons.Warnings.warn(SCons.Warnings.MandatoryWarning,
+                            "Foo")
+        assert to.out is None, to.out
+
         SCons.Warnings.enableWarningClass(SCons.Warnings.Warning)
         SCons.Warnings.warn(SCons.Warnings.DeprecatedWarning,
                             "Foo")
diff --git a/test/Deprecated/TaskmasterNeedsExecute.py b/test/Deprecated/TaskmasterNeedsExecute.py
new file mode 100644
index 0000000..6aedf59
--- /dev/null
+++ b/test/Deprecated/TaskmasterNeedsExecute.py
@@ -0,0 +1,58 @@
+#!/usr/bin/env python
+#
+# __COPYRIGHT__
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+
+__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"
+
+"""
+Verify the message about the deprecated Taskmaster.needs_task()
+method, and the ability to suppress it.
+"""
+
+import TestSCons
+
+test = TestSCons.TestSCons(match = TestSCons.match_re_dotall)
+
+test.write('SConstruct', """
+import SCons.Taskmaster
+tm = SCons.Taskmaster.Taskmaster()
+task = SCons.Taskmaster.Task(tm, [], True, None)
+task.needs_execute()
+""")
+
+expect = """
+scons: warning: Direct use of the Taskmaster.Task class will be deprecated
+\tin a future release.
+"""
+
+test.run(arguments = '.')
+
+test.run(arguments = '--warn=taskmaster-needs-execute .',
+         stderr = TestSCons.re_escape(expect) + TestSCons.file_expr)
+
+test.run(arguments = '--warn=no-taskmaster-needs-execute .')
+
+test.run(arguments = '--warn=future-deprecated .',
+         stderr = TestSCons.re_escape(expect) + TestSCons.file_expr)
+
+test.pass_test()