Merge branch 'master' into py36-depr

Author: bdbaddog

CHANGES.txt

@@ -9,6 +9,10 @@ NOTE: 4.3.0 now requires Python 3.6.0 and above. Python 3.5.x is no longer suppo
 
 RELEASE  VERSION/DATE TO BE FILLED IN LATER
 
+  From Thaddeus Crews:
+    - GetSConsVersion() to grab the latest SCons version without needing to
+      access SCons internals.
+
   From Raymond Li:
     - Fix issue #3935: OSErrors are now no longer hidden during execution of
       Actions. All exceptions during the execution of an Action are now
@@ -18,6 +22,12 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       expected exceptions (whereas previously many of these were silently
       caught and suppressed by the SCons Action exection code).
 
+  From Ryan Carsten Schmidt:
+    - Teach ParseFlags to put a --stdlib=libname argument into CXXFLAGS.
+      If placed in CCFLAGS (the default location), it could be fed to the
+      C compiler (gcc, clang) where it is not applicable and causes a
+      warning message.
+
   From Mats Wichmann:
     - Updated Value Node docs and tests.
     - Python 3.13 compat: re.sub deprecated count, flags as positional args,
@@ -32,6 +42,11 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       ones in parent NodeInfoBase and can just be inherited.
     - Update manpage for Tools, and for TOOL, which also gets a minor
       tweak for how it's handled (should be more accurate in a few situations).
+    - Test framework now uses a subdirectory named "scons" below the base
+      temporary directory. This gives something invariant to tell antivirus
+      to ignore without having to exclude tmpdir itself. Fixes #4509.
+    - MSVS "live" tests of project files adjusted to look for the generated
+      executable with an exe sufffix
     - Documentation build now properly passes through skipping the PDF
       (and EPUB) builds of manpage and user guide; this can also be done
       manually if directly calling doc/man/SConstruct and doc/user/SConstruct
@@ -41,6 +56,9 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - Add the ability to print a Variables object for debugging purposes
       (provides a __str__ method in the class).
     - Mark Python 3.6 support as deprecated.
+    - Clean up Variables: more consistently call them variables (finish the
+      old change from Options) in docstrings, etc.; some typing and other
+      tweaks.  Update manpage and user guide for Variables usage.
 
 
 RELEASE 4.7.0 -  Sun, 17 Mar 2024 17:22:20 -0700

RELEASE.txt

@@ -16,7 +16,7 @@ Here is a summary of the changes since 4.7.0:
 NEW FUNCTIONALITY
 -----------------
 
-- List new features (presumably why a checkpoint is being released)
+- GetSConsVersion() added to retrieve the SCons version.
 
 DEPRECATED FUNCTIONALITY
 ------------------------
@@ -40,6 +40,10 @@ CHANGED/ENHANCED EXISTING FUNCTIONALITY
   NOTE: With this change, user created Actions should now catch and handle
   expected exceptions (whereas previously many of these were silently caught
   and suppressed by the SCons Action exection code).
+- ParseFlags now sorts a --stdlib=libname argument into CXXFLAGS instead
+  of CCFLAGS; the latter variable could cause a compiler warning.
+- The implementation of Variables was slightly refactored, there should
+  not be user-visible changes.
 
 FIXES
 -----
@@ -49,9 +53,9 @@ FIXES
 IMPROVEMENTS
 ------------
 
-- List improvements that wouldn't be visible to the user in the
-  documentation:  performance improvements (describe the circumstances
-  under which they would be observed), or major code cleanups
+- Make the testing framework a little more resilient: the temporary
+  directory for tests now includes a component named "scons" which can
+  be given to antivirus software to exclude.
 
 PACKAGING
 ---------
@@ -64,6 +68,7 @@ DOCUMENTATION
 
 - Updated Value Node docs.
 - Update manpage for Tools, and for the TOOL variable.
+- Update manpage and user guide for Variables usage.
 
 
 

SCons/Environment.py

@@ -881,11 +881,11 @@ def ParseFlags(self, *flags) -> dict:
             'RPATH'         : [],
         }
 
-        def do_parse(arg) -> None:
-            # if arg is a sequence, recurse with each element
+        def do_parse(arg: Union[str, Sequence]) -> None:
             if not arg:
                 return
 
+            # if arg is a sequence, recurse with each element
             if not is_String(arg):
                 for t in arg: do_parse(t)
                 return
@@ -902,7 +902,7 @@ def append_define(name, mapping=mapping) -> None:
                 else:
                     mapping['CPPDEFINES'].append([t[0], '='.join(t[1:])])
 
-            # Loop through the flags and add them to the appropriate option.
+            # Loop through the flags and add them to the appropriate variable.
             # This tries to strike a balance between checking for all possible
             # flags and keeping the logic to a finite size, so it doesn't
             # check for some that don't occur often.  It particular, if the
@@ -926,6 +926,8 @@ def append_define(name, mapping=mapping) -> None:
             append_next_arg_to = None   # for multi-word args
             for arg in params:
                 if append_next_arg_to:
+                    # these are the second pass for options where the
+                    # option-argument follows as a second word.
                     if append_next_arg_to == 'CPPDEFINES':
                         append_define(arg)
                     elif append_next_arg_to == '-include':
@@ -1022,6 +1024,8 @@ def append_define(name, mapping=mapping) -> None:
                     else:
                         key = 'CFLAGS'
                     mapping[key].append(arg)
+                elif arg.startswith('-stdlib='):
+                    mapping['CXXFLAGS'].append(arg)
                 elif arg[0] == '+':
                     mapping['CCFLAGS'].append(arg)
                     mapping['LINKFLAGS'].append(arg)

SCons/Environment.xml

@@ -2687,6 +2687,7 @@ and added to the following construction variables:
 -openmp                 CCFLAGS, LINKFLAGS
 -pthread                CCFLAGS, LINKFLAGS
 -std=                   CFLAGS
+-stdlib=                CXXFLAGS
 -Wa,                    ASFLAGS, CCFLAGS
 -Wl,-rpath=             RPATH
 -Wl,-R,                 RPATH

SCons/EnvironmentTests.py

@@ -822,6 +822,7 @@ def test_ParseFlags(self) -> None:
             "-DFOO -DBAR=value -D BAZ "
             "-fsanitize=memory "
             "-fsanitize-address-use-after-return "
+            "-stdlib=libc++"
         )
 
         d = env.ParseFlags(s)
@@ -841,7 +842,7 @@ def test_ParseFlags(self) -> None:
                                 '+DD64',
                                 '-fsanitize=memory',
                                 '-fsanitize-address-use-after-return'], repr(d['CCFLAGS'])
-        assert d['CXXFLAGS'] == ['-std=c++0x'], repr(d['CXXFLAGS'])
+        assert d['CXXFLAGS'] == ['-std=c++0x', '-stdlib=libc++'], repr(d['CXXFLAGS'])
         assert d['CPPDEFINES'] == ['FOO', ['BAR', 'value'], 'BAZ'], d['CPPDEFINES']
         assert d['CPPFLAGS'] == ['-Wp,-cpp'], d['CPPFLAGS']
         assert d['CPPPATH'] == ['/usr/include/fum',

SCons/Script/SConscript.py

@@ -45,6 +45,7 @@
 import sys
 import traceback
 import time
+from typing import Tuple
 
 class SConscriptReturn(Exception):
     pass
@@ -385,7 +386,7 @@ class SConsEnvironment(SCons.Environment.Base):
     # Private methods of an SConsEnvironment.
     #
     @staticmethod
-    def _get_major_minor_revision(version_string):
+    def _get_major_minor_revision(version_string: str) -> Tuple[int, int, int]:
         """Split a version string into major, minor and (optionally)
         revision parts.
 
@@ -484,15 +485,22 @@ def Default(self, *targets) -> None:
         SCons.Script._Set_Default_Targets(self, targets)
 
     @staticmethod
-    def EnsureSConsVersion(major, minor, revision: int=0) -> None:
+    def GetSConsVersion() -> Tuple[int, int, int]:
+        """Return the current SCons version.
+
+        .. versionadded:: 4.8.0
+        """
+        return SConsEnvironment._get_major_minor_revision(SCons.__version__)
+
+    @staticmethod
+    def EnsureSConsVersion(major: int, minor: int, revision: int = 0) -> None:
         """Exit abnormally if the SCons version is not late enough."""
         # split string to avoid replacement during build process
         if SCons.__version__ == '__' + 'VERSION__':
             SCons.Warnings.warn(SCons.Warnings.DevelopmentVersionWarning,
                 "EnsureSConsVersion is ignored for development version")
             return
-        scons_ver = SConsEnvironment._get_major_minor_revision(SCons.__version__)
-        if scons_ver < (major, minor, revision):
+        if SConsEnvironment.GetSConsVersion() < (major, minor, revision):
             if revision:
                 scons_ver_string = '%d.%d.%d' % (major, minor, revision)
             else:

SCons/Script/SConscript.xml

@@ -136,6 +136,19 @@ EnsureSConsVersion(0,96,90)
 </summary>
 </scons_function>
 
+<scons_function name="GetSConsVersion">
+<arguments signature="global">
+()
+</arguments>
+<summary>
+<para>
+Returns the current SCons version in the form of a Tuple[int, int, int],
+representing the major, minor, and revision values respectively.
+<emphasis>Added in 4.7.1</emphasis>.
+</para>
+</summary>
+</scons_function>
+
 <scons_function name="Exit">
 <arguments signature="global">
 ([value])

SCons/Script/__init__.py

@@ -297,6 +297,7 @@ def Variables(files=None, args=ARGUMENTS):
 #
 # Static functions that do not trigger initialization of
 # DefaultEnvironment() and don't use its state.
+GetSConsVersion = _SConscript.SConsEnvironment.GetSConsVersion
 EnsureSConsVersion = _SConscript.SConsEnvironment.EnsureSConsVersion
 EnsurePythonVersion = _SConscript.SConsEnvironment.EnsurePythonVersion
 Exit = _SConscript.SConsEnvironment.Exit

SCons/Variables/BoolVariable.py

@@ -27,7 +27,7 @@
 
     opts = Variables()
     opts.Add(BoolVariable('embedded', 'build for an embedded system', False))
-    ...
+    env = Environment(variables=opts)
     if env['embedded']:
         ...
 """
@@ -54,13 +54,13 @@ def _text2bool(val: str) -> bool:
     Raises:
         ValueError: if *val* cannot be converted to boolean.
     """
-
     lval = val.lower()
     if lval in TRUE_STRINGS:
         return True
     if lval in FALSE_STRINGS:
         return False
-    raise ValueError("Invalid value for boolean option: %s" % val)
+    # TODO: leave this check to validator?
+    raise ValueError(f"Invalid value for boolean variable: {val!r}")
 
 
 def _validator(key, val, env) -> None:
@@ -73,23 +73,25 @@ def _validator(key, val, env) -> None:
     Raises:
         KeyError: if *key* is not set in *env*
         UserError: if the value of *key* is not ``True`` or ``False``.
-    """
-    if not env[key] in (True, False):
-        raise SCons.Errors.UserError(
-            'Invalid value for boolean option %s: %s' % (key, env[key])
-        )
 
+    """
+    if env[key] not in (True, False):
+        msg = f'Invalid value for boolean variable {key!r}: {env[key]}'
+        raise SCons.Errors.UserError(msg) from None
 
-def BoolVariable(key, help, default) -> Tuple[str, str, str, Callable, Callable]:
+# lint: W0622: Redefining built-in 'help' (redefined-builtin)
+def BoolVariable(key, help: str, default) -> Tuple[str, str, str, Callable, Callable]:
     """Return a tuple describing a boolean SCons Variable.
 
-    The input parameters describe a boolean option. Returns a tuple
-    including the correct converter and validator.
-    The *help* text will have ``(yes|no)`` automatically appended to show the
-    valid values. The result is usable as input to :meth:`Add`.
+    The input parameters describe a boolean variable, using a string
+    value as described by :const:`TRUE_STRINGS` and :const:`FALSE_STRINGS`.
+    Returns a tuple including the correct converter and validator.
+    The *help* text will have ``(yes|no)`` automatically appended to
+    show the valid values. The result is usable as input to
+    :meth:`~SCons.Variables.Variables.Add`.
     """
-    help = '%s (yes|no)' % help
-    return (key, help, default, _validator, _text2bool)
+    help = f'{help} (yes|no)'
+    return key, help, default, _validator, _text2bool
 
 # Local Variables:
 # tab-width:4

SCons/Variables/BoolVariableTests.py

@@ -67,18 +67,14 @@ def test_converter(self) -> None:
 
         for t in true_values:
             x = o.converter(t)
-            assert x, "converter returned false for '%s'" % t
+            assert x, f"converter returned False for {t!r}"
 
         for f in false_values:
             x = o.converter(f)
-            assert not x, "converter returned true for '%s'" % f
+            assert not x, f"converter returned True for {f!r}"
 
-        caught = False
-        try:
+        with self.assertRaises(ValueError):
             o.converter('x')
-        except ValueError:
-            caught = True
-        assert caught, "did not catch expected ValueError for 'x'"
 
     def test_validator(self) -> None:
         """Test the BoolVariable validator"""
@@ -98,19 +94,11 @@ def test_validator(self) -> None:
         o.validator('F', 0, env)
 
         # negative checks
-        caught = False
-        try:
+        with self.assertRaises(SCons.Errors.UserError):
             o.validator('N', 0, env)
-        except SCons.Errors.UserError:
-            caught = True
-        assert caught, "did not catch expected UserError for value %s" % env['N']
 
-        caught = False
-        try:
+        with self.assertRaises(KeyError):
             o.validator('NOSUCHKEY', 0, env)
-        except KeyError:
-            caught = True
-        assert caught, "did not catch expected KeyError for 'NOSUCHKEY'"
 
 
 if __name__ == "__main__":