AddOption now recognizes "settable" option

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.

There was a TODO in SCons/Script/SConsOptions.py about removing
three hardcoded ninja options in the "settable" list once this
change was made. When that was done it turned out one test failed,
because it called the SetOption before the ninja tool was initialized.
Logic reordered in the test, but this is a thing to watch out for.

Closes SCons#3983.

Signed-off-by: Mats Wichmann <[email protected]>

Author: mwichmann

CHANGES.txt

@@ -99,6 +99,9 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       SCons.Environment to SCons.Util to avoid the chance of import loops. Variables
       and Environment both use the routine and Environment() uses a Variables()
       object so better to move to a safer location.
+    - 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.
 
 
 RELEASE 4.7.0 -  Sun, 17 Mar 2024 17:22:20 -0700

RELEASE.txt

@@ -53,6 +53,9 @@ 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.
 
 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>