Merge branch 'master' into perf/env-setitem

Author: bdbaddog

.appveyor.yml

@@ -8,7 +8,7 @@ image:
   # linux builds done in Travis CI for now
   - Visual Studio 2017
   - Visual Studio 2019
-  - Visual Studio 2022
+  #- Visual Studio 2022  XXX Temporary disable while failing on .10 versions
 
 cache:
   - downloads -> appveyor.yml

CHANGES.txt

@@ -102,6 +102,18 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - Performance tweak: the __setitem__ method of an Environment, used for
       setting construction variables, now uses the string method isidentifier
       to validate the name (updated from microbenchmark results).
+    - AddOption and the internal add_local_option which AddOption calls now
+      recognize a "settable" keyword argument to indicate a project-added
+      option can also be modified using SetOption. Fixes #3983.
+      NOTE: If you were using ninja and using SetOption() for ninja options
+      in your SConscripts prior to loading the ninja tool, you will now
+      see an error. The fix is to move the SetOption() to after you've loaded
+      the ninja tool.
+    - ListVariable now has a separate validator, with the functionality
+      that was previously part of the converter. The main effect is to
+      allow a developer to supply a custom validator, which previously
+      could be inhibited by the converter failing before the validator
+      is reached.
 
 
 RELEASE 4.7.0 -  Sun, 17 Mar 2024 17:22:20 -0700

RELEASE.txt

@@ -53,6 +53,18 @@ CHANGED/ENHANCED EXISTING FUNCTIONALITY
 - The Variables object Add method now accepts a subst keyword argument
   (defaults to True) which can be set to inhibit substitution prior to
   calling the variable's converter and validator.
+- AddOption and the internal add_local_option which AddOption calls now
+  recognize a "settable" keyword argument to indicate a project-added
+  option can also be modified using SetOption.
+  NOTE: If you were using ninja and using SetOption() for ninja options
+  in your SConscripts prior to loading the ninja tool, you will now
+  see an error. The fix is to move the SetOption() to after you've loaded
+  the ninja tool.
+- ListVariable now has a separate validator, with the functionality
+  that was previously part of the converter. The main effect is to
+  allow a developer to supply a custom validator, which previously
+  could be inhibited by the converter failing before the validator
+  is reached.
 
 FIXES
 -----

SCons/Script/Main.py

@@ -41,7 +41,7 @@
 import traceback
 import platform
 import threading
-from typing import Optional, List
+from typing import Optional, List, TYPE_CHECKING
 
 import SCons.CacheDir
 import SCons.Debug
@@ -59,6 +59,8 @@
 import SCons.Util
 import SCons.Warnings
 import SCons.Script.Interactive
+if TYPE_CHECKING:
+    from SCons.Script import SConsOption
 from SCons.Util.stats import count_stats, memory_stats, time_stats, ENABLE_JSON, write_scons_stats_file, JSON_OUTPUT_FILE
 
 from SCons import __version__ as SConsVersion
@@ -174,6 +176,7 @@ def __call__(self, node) -> None:
 ProgressObject = SCons.Util.Null()
 
 def Progress(*args, **kw) -> None:
+    """Show progress during building - Public API."""
     global ProgressObject
     ProgressObject = Progressor(*args, **kw)
 
@@ -501,29 +504,47 @@ def __getattr__(self, attr):
     # TODO: to quiet checkers, FakeOptionParser should also define
     #   raise_exception_on_error, preserve_unknown_options, largs and parse_args
 
-    def add_local_option(self, *args, **kw) -> None:
+    def add_local_option(self, *args, **kw) -> "SConsOption":
         pass
 
 
 OptionsParser = FakeOptionParser()
 
-def AddOption(*args, **kw):
+def AddOption(*args, settable: bool = False, **kw) -> "SConsOption":
+    """Add a local option to the option parser - Public API.
+
+    If the *settable* parameter is true, the option will be included in the
+    list of settable options; all other keyword arguments are passed on to
+    :meth:`~SCons.Script.SConsOptions.SConsOptionParser.add_local_option`.
+
+    .. versionchanged:: 4.8.0
+       The *settable* parameter added to allow including the new option
+       to the table of options eligible to use :func:`SetOption`.
+
+    """
     if 'default' not in kw:
         kw['default'] = None
+    kw['settable'] = settable
     result = OptionsParser.add_local_option(*args, **kw)
     return result
 
-def GetOption(name):
+def GetOption(name: str):
+    """Get the value from an option - Public API."""
     return getattr(OptionsParser.values, name)
 
-def SetOption(name, value):
+def SetOption(name: str, value):
+    """Set the value of an option - Public API."""
     return OptionsParser.values.set_option(name, value)
 
-def DebugOptions(json=None):
-    """
-    API to allow specifying options to SCons debug logic
-    Currently only json is supported which changes the
-    json file written by --debug=json from the default
+def DebugOptions(json: Optional[str] = None) -> None:
+    """Specify options to SCons debug logic - Public API.
+
+    Currently only *json* is supported, which changes the JSON file
+    written to if the ``--debug=json`` command-line option is specified
+    to the value supplied.
+
+    .. versionadded:: 4.6.0
+
     """
     if json is not None:
         json_node = SCons.Defaults.DefaultEnvironment().arg2nodes(json)
@@ -540,7 +561,7 @@ def DebugOptions(json=None):
             raise SCons.Errors.UserError(f"Unable to create directory for JSON debug output file: {SCons.Util.stats.JSON_OUTPUT_FILE}")
 
 
-def ValidateOptions(throw_exception: bool=False) -> None:
+def ValidateOptions(throw_exception: bool = False) -> None:
     """Validate options passed to SCons on the command line.
 
     Checks that all options given on the command line are known to this

SCons/Script/Main.xml

@@ -93,21 +93,25 @@ the option value may be accessed using
 &f-link-GetOption;
 or
 &f-link-env-GetOption;.
-&f-link-SetOption; is not currently supported for
-options added with &f-AddOption;.
-<!-- was:
-The value may also be set using
-&f-SetOption;
+If the <parameter>settable=True</parameter> argument
+was supplied in the &AddOption; call,
+the value may also be set later using
+&f-link-SetOption;
 or
-&f-env.SetOption;,
-if conditions in a
-&SConscript;
+&f-link-env-SetOption;,
+if conditions in an
+&SConscript; file
 require overriding any default value.
 Note however that a
 value specified on the command line will
 <emphasis>always</emphasis>
-override a value set by any SConscript file.
--->
+override a value set in an SConscript file.
+</para>
+
+<para>
+<emphasis>Changed in 4.8.0</emphasis>: added the
+<parameter>settable</parameter> keyword argument
+to enable an added option to be settable via &SetOption;.
 </para>
 
 <para>
@@ -196,6 +200,7 @@ Allows setting options for SCons debug options. Currently the only supported val
   <example_commands>
 DebugOptions(json='#/build/output/scons_stats.json')
 </example_commands>
+<para><emphasis>New in version 4.6.0.</emphasis></para>
 </summary>
 </scons_function>
 
@@ -334,9 +339,10 @@ atexit.register(print_build_failures)
 <summary>
 <para>
 Query the value of settable options which may have been set
-on the command line, or by using the &f-link-SetOption; function.
+on the command line, via option defaults,
+or by using the &f-link-SetOption; function.
 The value of the option is returned in a type matching how the
-option was declared - see the documentation for the
+option was declared - see the documentation of the
 corresponding command line option for information about each specific
 option.
 </para>
@@ -801,6 +807,16 @@ are not settable using &f-SetOption; since those files must
 be read in order to find the &f-SetOption; call in the first place.
 </para>
 
+<para>
+For project-specific options (sometimes called
+<firstterm>local options</firstterm>)
+added via an &f-link-AddOption; call,
+&f-SetOption; is available only after the
+&f-AddOption; call has completed successfully,
+and only if that call included the
+<parameter>settable=True</parameter> argument.
+</para>
+
 <para>
 The settable variables with their associated command-line options are:
 </para>