Merge pull request #4217 from bdbaddog/add_api_to_check_for_invalid_options_issue_4187

Add ValidateOption() API

Author: bdbaddog

CHANGES.txt

@@ -9,6 +9,11 @@ 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 William Deegan:
+    - Added ValidateOptions() which will check that all command line options are in either
+      those specified by SCons itself, or by AddOption() in SConstruct/SConscript.  It should
+      not be called until all AddOption() calls are completed. Resolves Issue #4187
+
   From Dan Mezhiborsky:
     - Add newline to end of compilation db (compile_commands.json).
 

RELEASE.txt

@@ -16,7 +16,9 @@ Here is a summary of the changes since 4.4.0:
 NEW FUNCTIONALITY
 -----------------
 
-- List new features (presumably why a checkpoint is being released)
+- Added ValidateOptions() which will check that all command line options are in either
+  those specified by SCons itself, or by AddOption() in SConstruct/SConscript.  It should
+  not be called until all AddOption() calls are completed. Resolves Issue #4187
 
 DEPRECATED FUNCTIONALITY
 ------------------------

SCons/Script/Main.py

@@ -492,6 +492,26 @@ def GetOption(name):
 def SetOption(name, value):
     return OptionsParser.values.set_option(name, value)
 
+
+def ValidateOptions(throw_exception=False) -> None:
+    """Validate options passed to SCons on the command line.
+
+    If you call this after you set all your command line options with AddOption(),
+    it will verify that all command line options are valid.
+    So if you added an option --xyz and you call SCons with --xyy you can cause
+    SCons to issue an error message and exit by calling this function.
+
+    :param bool throw_exception: (Optional) Should this function raise an error if there's an invalid option on the command line, or issue a message and exit with error status.
+
+    :raises SConsBadOptionError: If throw_exception is True and there are invalid options on command line.
+
+    .. versionadded:: 4.4.1
+    """
+
+    OptionsParser.raise_exception_on_error = throw_exception
+    OptionsParser.preserve_unknown_options = False
+    OptionsParser.parse_args(OptionsParser.largs, OptionsParser.values)
+
 def PrintHelp(file=None):
     OptionsParser.print_help(file=file)
 
@@ -1364,6 +1384,7 @@ def _exec_main(parser, values):
     else:
         _main(parser)
 
+
 def main():
     global OptionsParser
     global exit_status

SCons/Script/Main.xml

@@ -740,6 +740,7 @@ Multiple targets can be passed in to a single call to
 </para>
 </summary>
 </scons_function>
+
 <scons_function name="SetOption">
 <arguments>
 (name, value)
@@ -943,6 +944,68 @@ Example:
 SetOption('max_drift', 0)
 </example_commands>
 </summary>
+
+
 </scons_function>
 
+    <scons_function name="ValidateOptions">
+        <arguments signature="global">
+            ([throw_exception=False])
+        </arguments>
+
+        <summary>
+            <para>
+                Check that all the options specified on the command line are either defined by SCons itself
+                or defined by calls to &f-link-AddOption;.
+            </para>
+            <para>
+                This function should only be called after the last &f-link-AddOption; call in your &SConscript;
+                logic.
+            </para>
+            <para>
+                Be aware that some tools call &f-link-AddOption;, if you are getting error messages for arguments
+                that they add, you will need to ensure that you load those tools before you call &f-ValidateOptions;.
+            </para>
+            <para>
+                If there are any command line options not defined, calling this function will cause SCons to issue an
+                error message and then exit with an error exit
+                status.</para>
+            <para>If the optional <parameter>throw_exception</parameter> is <literal>True</literal>, &f-ValidateOptions; will raise a
+                <exceptionname>SConsBadOptionError</exceptionname>
+                exception. This would allow the calling
+                &SConscript; logic can catch that exception and handle invalid options itself.
+            </para>
+
+            <para>
+                Example:
+            </para>
+
+            <example_commands>
+try:
+    ValidateOptions(throw_exception=True)
+except SConsBadOptionError as e:
+    print("Parser is SConsOptionParser:%s" % (isinstance(e.parser, SConsOptionParser)))
+    print("Message is :%s" % e.opt_str)
+    Exit(3)
+            </example_commands>
+
+            <para>
+                This function is useful to force SCons to fail fast before you execute any expensive logic later in your
+                build logic.
+                For example if you specify build options via any flags, a simple typo could yield the incorrect build
+                option throughout your entire build.
+            </para>
+            <example_commands>
+scons --compilers=mingw (the correct flag is --compiler)
+            </example_commands>
+            <para>
+                Could cause SCons to run configure steps with the incorrect compiler. Costing developer time trying to
+                track down why the configure logic failed with a compiler which should work.
+            </para>
+
+
+
+        </summary>
+    </scons_function>
+
 </sconsdoc>

SCons/Script/SConsOptions.py

@@ -289,14 +289,36 @@ def format_help(self, formatter):
         return result
 
 
+class SConsBadOptionError(optparse.BadOptionError):
+    """Exception used to indicate that invalid command line options were specified
+
+    :ivar str opt_str: The offending option specified on command line which is not recognized
+    :ivar OptionParser parser: The active argument parser
+
+    """
+
+    def __init__(self, opt_str, parser=None):
+        self.opt_str = opt_str
+        self.parser = parser
+
+    def __str__(self):
+        return _("no such option: %s") % self.opt_str
+
+
 class SConsOptionParser(optparse.OptionParser):
     preserve_unknown_options = False
+    raise_exception_on_error = False
 
     def error(self, msg):
-        # overridden OptionValueError exception handler
-        self.print_usage(sys.stderr)
-        sys.stderr.write("SCons Error: %s\n" % msg)
-        sys.exit(2)
+        """
+        overridden OptionValueError exception handler
+        """
+        if self.raise_exception_on_error:
+            raise SConsBadOptionError(msg, self)
+        else:
+            self.print_usage(sys.stderr)
+            sys.stderr.write("SCons Error: %s\n" % msg)
+            sys.exit(2)
 
     def _process_long_opt(self, rargs, values):
         """ SCons-specific processing of long options.

SCons/Script/SConscript.py

@@ -528,6 +528,7 @@ def GetOption(self, name):
         name = self.subst(name)
         return SCons.Script.Main.GetOption(name)
 
+
     def Help(self, text, append=False):
         text = self.subst(text, raw=1)
         SCons.Script.HelpFunction(text, append=append)

SCons/Script/__init__.py

@@ -107,6 +107,7 @@
 PrintHelp               = Main.PrintHelp
 GetOption               = Main.GetOption
 SetOption               = Main.SetOption
+ValidateOptions         = Main.ValidateOptions
 Progress                = Main.Progress
 GetBuildFailures        = Main.GetBuildFailures
 

SCons/__init__.py

@@ -1,9 +1,9 @@
-__version__="4.4.0"
+__version__="4.4.1"
 __copyright__="Copyright (c) 2001 - 2022 The SCons Foundation"
 __developer__="bdbaddog"
-__date__="Sat, 30 Jul 2022 14:11:34 -0700"
+__date__="Mon, 15 Aug 2022 11:59:33 -0700"
 __buildsys__="M1Dog2021"
-__revision__="fc8d0ec215ee6cba8bc158ad40c099be0b598297"
-__build__="fc8d0ec215ee6cba8bc158ad40c099be0b598297"
+__revision__="18745cfc5e75df8028682183097202f926e22134"
+__build__="18745cfc5e75df8028682183097202f926e22134"
 # make sure compatibility is always in place
 import SCons.compat # noqa

bin/update_doc_files.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+python bin/docs-update-generated.py
+python bin/docs-validate.py
+python bin/docs-create-example-outputs.py

doc/generated/examples/caching_ex-random_1.xml

@@ -1,8 +1,8 @@
 <screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q</userinput>
-cc -o f4.o -c f4.c
-cc -o f2.o -c f2.c
 cc -o f3.o -c f3.c
+cc -o f4.o -c f4.c
 cc -o f1.o -c f1.c
+cc -o f2.o -c f2.c
 cc -o f5.o -c f5.c
 cc -o prog f1.o f2.o f3.o f4.o f5.o
 </screen>