Make ${,UN}CHANGED_{SOURCES,TARGETS} into future reserved construction

variable names, with an appropriate warning.

6 files changed, 101 insertions, 16 deletions

diff --git a/src/CHANGES.txt b/src/CHANGES.txt
index 6b89aa7..f496fa7 100644
--- a/src/CHANGES.txt
+++ b/src/CHANGES.txt
@@ -74,6 +74,12 @@ RELEASE 1.X - XXX
     - Fix use of Glob() when a repository or source directory contains
       an in-memory Node without a corresponding on-disk file or directory.
 
+    - Add a warning about future reservation of $CHANGED_SOURCES,
+      $CHANGED_TARGETS, $UNCHANGED_SOURCES and $UNCHANGED_TARGETS.
+
+    - Enable by default the existing warnings about setting the resource
+      $SOURCE, $SOURCES, $TARGET and $TARGETS variable.
+
   From Rob Managan:
 
     - Scan for TeX files in the paths specified in the $TEXINPUTS
diff --git a/src/RELEASE.txt b/src/RELEASE.txt
index 2bca531..223beb1 100644
--- a/src/RELEASE.txt
+++ b/src/RELEASE.txt
@@ -20,11 +20,32 @@ more effectively, please sign up for the scons-users mailing list at:
 
 
 
-RELEASE 1.1.0 - Thu, 09 Oct 2008 08:33:47 -0700
+RELEASE XXX -
 
   Please consult the CHANGES.txt file for a list of specific changes
   since last release.
 
+  Please note the following important changes since release 1.1.0:
+
+    --  THE $CHANGED_SOURCES, $CHANGED_TARGETS, $UNCHANGED_SOURCES
+        AND $UNCHANGED_TARGETS VARIABLES WILL BECOME RESERVED
+
+        A future release (probably 1.3.0) will make the construction
+        variable names $CHANGED_SOURCES, $CHANGED_TARGETS,
+        $UNCHANGED_SOURCES and $UNCHANGED_TARGETS into reserved
+        construction variable names controlled by SCons itself (like
+        the current $SOURCE, $TARGETS, etc.).
+
+        Setting these variable names in the current release will generate
+        a warning but still set the variables.  When they become reserved
+        variable names, they will generate a different warning message
+        and attempts to set these variables will be ignored.
+
+        SCons configurations that happen to use these variable names
+        should be changed to use different variable names, in order
+        to ensure that the configuration continues to work with future
+        versions of SCons.
+
   Please note the following important changes since release 0.98.4:
 
     --  scons.bat NOW RETURNS THE REAL SCONS EXIT STATUS
diff --git a/src/engine/SCons/Environment.py b/src/engine/SCons/Environment.py
index 5b82086..f6123b9 100644
--- a/src/engine/SCons/Environment.py
+++ b/src/engine/SCons/Environment.py
@@ -105,24 +105,40 @@ def apply_tools(env, tools, toolpath):
         else:
             env.Tool(tool)
 
-# These names are controlled by SCons; users should never set or override
-# them.  This warning can optionally be turned off, but scons will still
-# ignore the illegal variable names even if it's off.
-reserved_construction_var_names = \
-    ['TARGET', 'TARGETS', 'SOURCE', 'SOURCES']
+# These names are (or will be) controlled by SCons; users should never
+# set or override them.  This warning can optionally be turned off,
+# but scons will still ignore the illegal variable names even if it's off.
+reserved_construction_var_names = [
+    'SOURCE',
+    'SOURCES',
+    'TARGET',
+    'TARGETS',
+]
+
+future_reserved_construction_var_names = [
+    'CHANGED_SOURCES',
+    'CHANGED_TARGETS',
+    'UNCHANGED_SOURCES',
+    'UNCHANGED_TARGETS',
+]
 
 def copy_non_reserved_keywords(dict):
     result = semi_deepcopy(dict)
     for k in result.keys():
         if k in reserved_construction_var_names:
-            SCons.Warnings.warn(SCons.Warnings.ReservedVariableWarning,
-                                "Ignoring attempt to set reserved variable `%s'" % k)
+            msg = "Ignoring attempt to set reserved variable `$%s'"
+            SCons.Warnings.warn(SCons.Warnings.ReservedVariableWarning, msg % k)
             del result[k]
     return result
 
 def _set_reserved(env, key, value):
-    msg = "Ignoring attempt to set reserved variable `%s'" % key
-    SCons.Warnings.warn(SCons.Warnings.ReservedVariableWarning, msg)
+    msg = "Ignoring attempt to set reserved variable `$%s'"
+    SCons.Warnings.warn(SCons.Warnings.ReservedVariableWarning, msg % key)
+
+def _set_future_reserved(env, key, value):
+    env._dict[key] = value
+    msg = "`$%s' will be reserved in a future release and setting it will become ignored"
+    SCons.Warnings.warn(SCons.Warnings.FutureReservedVariableWarning, msg % key)
 
 def _set_BUILDERS(env, key, value):
     try:
@@ -364,6 +380,8 @@ class SubstitutionEnvironment:
         self._special_set = {}
         for key in reserved_construction_var_names:
             self._special_set[key] = _set_reserved
+        for key in future_reserved_construction_var_names:
+            self._special_set[key] = _set_future_reserved
         self._special_set['BUILDERS'] = _set_BUILDERS
         self._special_set['SCANNERS'] = _set_SCANNERS
 
diff --git a/src/engine/SCons/EnvironmentTests.py b/src/engine/SCons/EnvironmentTests.py
index 2c09378..f3210b8 100644
--- a/src/engine/SCons/EnvironmentTests.py
+++ b/src/engine/SCons/EnvironmentTests.py
@@ -1120,25 +1120,59 @@ env4.builder1.env, env3)
         assert env.Dictionary('ENV')['PATH'] == '/foo:/bar'
 
     def test_ReservedVariables(self):
-        """Test generation of warnings when reserved variable names
-        are set in an environment."""
+        """Test warning generation when reserved variable names are set"""
 
-        SCons.Warnings.enableWarningClass(SCons.Warnings.ReservedVariableWarning)
+        reserved_variables = [
+            'SOURCE',
+            'SOURCES',
+            'TARGET',
+            'TARGETS',
+        ]
+
+        warning = SCons.Warnings.ReservedVariableWarning
+        SCons.Warnings.enableWarningClass(warning)
         old = SCons.Warnings.warningAsException(1)
 
         try:
             env4 = Environment()
-            for kw in ['TARGET', 'TARGETS', 'SOURCE', 'SOURCES']:
+            for kw in reserved_variables:
                 exc_caught = None
                 try:
                     env4[kw] = 'xyzzy'
-                except SCons.Warnings.ReservedVariableWarning:
+                except warning:
                     exc_caught = 1
                 assert exc_caught, "Did not catch ReservedVariableWarning for `%s'" % kw
                 assert not env4.has_key(kw), "`%s' variable was incorrectly set" % kw
         finally:
             SCons.Warnings.warningAsException(old)
 
+    def test_FutureReservedVariables(self):
+        """Test warning generation when future reserved variable names are set"""
+
+        future_reserved_variables = [
+            'CHANGED_SOURCES',
+            'CHANGED_TARGETS',
+            'UNCHANGED_SOURCES',
+            'UNCHANGED_TARGETS',
+        ]
+
+        warning = SCons.Warnings.FutureReservedVariableWarning
+        SCons.Warnings.enableWarningClass(warning)
+        old = SCons.Warnings.warningAsException(1)
+
+        try:
+            env4 = Environment()
+            for kw in future_reserved_variables:
+                exc_caught = None
+                try:
+                    env4[kw] = 'xyzzy'
+                except warning:
+                    exc_caught = 1
+                assert exc_caught, "Did not catch FutureReservedVariableWarning for `%s'" % kw
+                assert env4.has_key(kw), "`%s' variable was not set" % kw
+        finally:
+            SCons.Warnings.warningAsException(old)
+
     def test_IllegalVariables(self):
         """Test that use of illegal variables raises an exception"""
         env = Environment()
diff --git a/src/engine/SCons/Script/Main.py b/src/engine/SCons/Script/Main.py
index 2d4e6a0..25e73dc 100644
--- a/src/engine/SCons/Script/Main.py
+++ b/src/engine/SCons/Script/Main.py
@@ -737,6 +737,7 @@ def _main(parser):
     default_warnings = [ SCons.Warnings.CorruptSConsignWarning,
                          SCons.Warnings.DeprecatedWarning,
                          SCons.Warnings.DuplicateEnvironmentWarning,
+                         SCons.Warnings.FutureReservedVariableWarning,
                          SCons.Warnings.LinkWarning,
                          SCons.Warnings.MissingSConscriptWarning,
                          SCons.Warnings.NoMD5ModuleWarning,
@@ -744,7 +745,9 @@ def _main(parser):
                          SCons.Warnings.NoObjectCountWarning,
                          SCons.Warnings.NoParallelSupportWarning,
                          SCons.Warnings.MisleadingKeywordsWarning,
-                         SCons.Warnings.StackSizeWarning, ]
+                         SCons.Warnings.ReservedVariableWarning,
+                         SCons.Warnings.StackSizeWarning,
+                       ]
 
     for warning in default_warnings:
         SCons.Warnings.enableWarningClass(warning)
diff --git a/src/engine/SCons/Warnings.py b/src/engine/SCons/Warnings.py
index 5af9263..03ab9ae 100644
--- a/src/engine/SCons/Warnings.py
+++ b/src/engine/SCons/Warnings.py
@@ -64,6 +64,9 @@ class DeprecatedTargetSignaturesWarning(DeprecatedWarning):
 class DuplicateEnvironmentWarning(Warning):
     pass
 
+class FutureReservedVariableWarning(Warning):
+    pass
+
 class LinkWarning(Warning):
     pass