Tweak Append/Prepend e2e tests

Added another try block so complete prepend e2e test can be run
on a branch where PR  #4263 is not applied (for comparison).
Added license header.

Changed invalid-tuple unittest to use assertRaises (behavior
is the same)

Also added a versionadded and a versionchanged to docstrings.

Signed-off-by: Mats Wichmann <mats@linux.com>

5 files changed, 49 insertions, 17 deletions

diff --git a/SCons/Defaults.py b/SCons/Defaults.py
index 72af1bd98..4ca7ab86d 100644
--- a/SCons/Defaults.py
+++ b/SCons/Defaults.py
@@ -520,6 +520,11 @@ def processDefines(defs) -> List[str]:
     or direct write) it can be a multitude of types.
 
     Any prefix/suffix is handled elsewhere (usually :func:`_concat_ixes`).
+
+    .. versionchanged:: 4.5
+       Bare tuples are now treated the same as tuple-in-sequence, assumed
+       to describe a valued macro. Bare strings are now split on space.
+       A dictionary is no longer sorted before handling.
     """
     dlist = []
     if is_List(defs):
diff --git a/SCons/DefaultsTests.py b/SCons/DefaultsTests.py
index 66e219a89..b23f3285e 100644
--- a/SCons/DefaultsTests.py
+++ b/SCons/DefaultsTests.py
@@ -147,12 +147,10 @@ class DefaultsTestCase(unittest.TestCase):
 
         with self.subTest():
             # invalid tuple
-            try:
+            with self.assertRaises(
+                UserError, msg="Invalid tuple should throw SCons.Errors.UserError"
+            ):
                 rv = processDefines([('name', 'val', 'bad')])
-            except UserError as e:
-                pass
-            else:
-                self.fail("Invalid tuple should throw SCons.Errors.UserError")
 
 
 if __name__ == "__main__":
diff --git a/SCons/Environment.py b/SCons/Environment.py
index 3bd1a6204..74c564174 100644
--- a/SCons/Environment.py
+++ b/SCons/Environment.py
@@ -201,7 +201,7 @@ def _add_cppdefines(
     unique: bool = False,
     delete_existing: bool = False,
 ) -> None:
-    """Adds to CPPDEFINES, using the rules for C preprocessor macros.
+    """Adds to ``CPPDEFINES``, using the rules for C preprocessor macros.
 
     This is split out from regular construction variable addition because
     these entries can express either a macro with a replacement value or
@@ -222,6 +222,8 @@ def _add_cppdefines(
         prepend: whether to put *val* in front or back.
         unique: whether to add *val* if it already exists.
         delete_existing: if *unique* is true, add *val* after removing previous.
+
+    .. versionadded:: 4.5
     """
 
     def _add_define(item, defines: deque, prepend: bool = False) -> None:
diff --git a/test/CPPDEFINES/fixture/SConstruct-Append b/test/CPPDEFINES/fixture/SConstruct-Append
index 1149fc33b..8c26270f3 100644
--- a/test/CPPDEFINES/fixture/SConstruct-Append
+++ b/test/CPPDEFINES/fixture/SConstruct-Append
@@ -1,3 +1,9 @@
+# SPDX-License-Identifier: MIT
+#
+# Copyright The SCons Foundation
+
+"""Append/AppendUnique tests"""
+
 DefaultEnvironment(tools=[])
 
 # Special cases:
@@ -22,14 +28,17 @@ env_multi = Environment(CPPDEFPREFIX='-D')
 env_multi['CPPDEFINES'] = "foo bar"
 env_multi.Append(CPPDEFINES="baz")
 print(env_multi.subst('$_CPPDEFFLAGS'))
+
 env_multi = Environment(CPPDEFPREFIX='-D')
 env_multi['CPPDEFINES'] = ["foo bar"]
 env_multi.Append(CPPDEFINES="baz")
 print(env_multi.subst('$_CPPDEFFLAGS'))
+
 env_multi = Environment(CPPDEFPREFIX='-D')
 env_multi['CPPDEFINES'] = "foo"
 env_multi.Append(CPPDEFINES=["bar baz"])
 print(env_multi.subst('$_CPPDEFFLAGS'))
+
 env_multi = Environment(CPPDEFPREFIX='-D')
 env_multi['CPPDEFINES'] = "foo"
 env_multi.Append(CPPDEFINES="bar baz")
@@ -40,11 +49,15 @@ print(env_multi.subst('$_CPPDEFFLAGS'))
 # so we expect a reordered list, but with the same macro defines.
 env_multi = Environment(CPPDEFPREFIX='-D')
 env_multi.Append(CPPDEFINES=["Macro1=Value1", ("Macro2", "Value2"), {"Macro3": "Value3"}, "Macro4"])
-env_multi.AppendUnique(CPPDEFINES="Macro2=Value2", delete_existing=True)
-env_multi.AppendUnique(CPPDEFINES=[("Macro4", None)], delete_existing=True)
-env_multi.AppendUnique(CPPDEFINES=[("Macro3", "Value3")], delete_existing=True)
-env_multi.AppendUnique(CPPDEFINES={"Macro1": "Value1"}, delete_existing=True)
-print(env_multi.subst('$_CPPDEFFLAGS'))
+try:
+    env_multi.AppendUnique(CPPDEFINES="Macro2=Value2", delete_existing=True)
+    env_multi.AppendUnique(CPPDEFINES=[("Macro4", None)], delete_existing=True)
+    env_multi.AppendUnique(CPPDEFINES=[("Macro3", "Value3")], delete_existing=True)
+    env_multi.AppendUnique(CPPDEFINES={"Macro1": "Value1"}, delete_existing=True)
+except Exception as t:
+    print(f"Prepend FAILED: {t}")
+else:
+    print(env_multi.subst('$_CPPDEFFLAGS'))
 
 # A lone tuple handled differently than a lone list.
 env_multi = Environment(CPPDEFPREFIX='-D', CPPDEFINES=("Macro1", "Value1"))
diff --git a/test/CPPDEFINES/fixture/SConstruct-Prepend b/test/CPPDEFINES/fixture/SConstruct-Prepend
index 67d637cd4..26546f113 100644
--- a/test/CPPDEFINES/fixture/SConstruct-Prepend
+++ b/test/CPPDEFINES/fixture/SConstruct-Prepend
@@ -1,4 +1,11 @@
+# SPDX-License-Identifier: MIT
+#
+# Copyright The SCons Foundation
+
+"""Prepend/PrependUnique tests"""
+
 DefaultEnvironment(tools=[])
+
 # Special cases:
 # https://github.com/SCons/scons/issues/1738
 env_1738_2 = Environment(CPPDEFPREFIX='-D')
@@ -21,29 +28,36 @@ env_multi = Environment(CPPDEFPREFIX='-D')
 env_multi['CPPDEFINES'] = "foo bar"
 env_multi.Prepend(CPPDEFINES="baz")
 print(env_multi.subst('$_CPPDEFFLAGS'))
+
 env_multi = Environment(CPPDEFPREFIX='-D')
 env_multi['CPPDEFINES'] = ["foo bar"]
 env_multi.Prepend(CPPDEFINES="baz")
 print(env_multi.subst('$_CPPDEFFLAGS'))
+
 env_multi = Environment(CPPDEFPREFIX='-D')
 env_multi['CPPDEFINES'] = "foo"
 env_multi.Prepend(CPPDEFINES=["bar baz"])
 print(env_multi.subst('$_CPPDEFFLAGS'))
+
 env_multi = Environment(CPPDEFPREFIX='-D')
 env_multi['CPPDEFINES'] = "foo"
 env_multi.Prepend(CPPDEFINES="bar baz")
 print(env_multi.subst('$_CPPDEFFLAGS'))
 
-# Check that AppendUnique(..., delete_existing=True) works as expected.
+# Check that PrependUnique(..., delete_existing=True) works as expected.
 # Each addition is in different but matching form, and different order
 # so we expect a reordered list, but with the same macro defines.
 env_multi = Environment(CPPDEFPREFIX='-D')
 env_multi.Prepend(CPPDEFINES=["Macro1=Value1", ("Macro2", "Value2"), {"Macro3": "Value3"}])
-env_multi.PrependUnique(CPPDEFINES="Macro2=Value2", delete_existing=True)
-env_multi.AppendUnique(CPPDEFINES=[("Macro4", None)], delete_existing=True)
-env_multi.PrependUnique(CPPDEFINES=[("Macro3", "Value3")], delete_existing=True)
-env_multi.PrependUnique(CPPDEFINES={"Macro1": "Value1"}, delete_existing=True)
-print(env_multi.subst('$_CPPDEFFLAGS'))
+try:
+    env_multi.PrependUnique(CPPDEFINES="Macro2=Value2", delete_existing=True)
+    env_multi.PrependUnique(CPPDEFINES=[("Macro4", None)], delete_existing=True)
+    env_multi.PrependUnique(CPPDEFINES=[("Macro3", "Value3")], delete_existing=True)
+    env_multi.PrependUnique(CPPDEFINES={"Macro1": "Value1"}, delete_existing=True)
+except Exception as t:
+    print(f"Prepend FAILED: {t}")
+else:
+    print(env_multi.subst('$_CPPDEFFLAGS'))
 
 # A lone tuple handled differently than a lone list.
 env_tuple = Environment(CPPDEFPREFIX='-D', CPPDEFINES=("Macro1", "Value1"))