From 764fb465a45f10adec4d4b904abd78ce731a0f8a Mon Sep 17 00:00:00 2001 From: William Deegan Date: Tue, 16 Aug 2022 21:51:31 -0700 Subject: rework the docs --- SCons/Script/Main.xml | 41 +++++++++++++++--------- doc/generated/examples/caching_ex-random_1.xml | 6 ++-- doc/generated/functions.gen | 43 ++++++++++++++++++-------- 3 files changed, 60 insertions(+), 30 deletions(-) diff --git a/SCons/Script/Main.xml b/SCons/Script/Main.xml index efec64f..ec09d35 100644 --- a/SCons/Script/Main.xml +++ b/SCons/Script/Main.xml @@ -959,18 +959,6 @@ SetOption('max_drift', 0) or defined by calls to &f-link-AddOption;. - 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. - - - If optional throw_exception is True, &f-ValidateOptions; will raise a - SConsBadOptionError - exception instead of printing an error message and exiting with an error status. Then the calling - &SConscript; logic can catch that exception and handle invalid options itself. - - - This function should only be called after the last &f-link-AddOption; call in your &SConscript; logic. @@ -978,19 +966,44 @@ SetOption('max_drift', 0) 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;. + + 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. + If the optional throw_exception is True, &f-ValidateOptions; will raise a + SConsBadOptionError + exception. This would allow the calling + &SConscript; logic can catch that exception and handle invalid options itself. + Example: - + 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) - + + + + 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. + + +scons --compilers=mingw (the correct flag is --compiler) + + + 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. + + + diff --git a/doc/generated/examples/caching_ex-random_1.xml b/doc/generated/examples/caching_ex-random_1.xml index a2de9bd..2e3b879 100644 --- a/doc/generated/examples/caching_ex-random_1.xml +++ b/doc/generated/examples/caching_ex-random_1.xml @@ -1,8 +1,8 @@ % scons -Q -cc -o f2.o -c f2.c -cc -o f5.o -c f5.c -cc -o f1.o -c f1.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 diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen index 6deda59..1c580f5 100644 --- a/doc/generated/functions.gen +++ b/doc/generated/functions.gen @@ -4388,17 +4388,7 @@ the tool object, previously it did not return ValidateOptions([throw_exception=False]) Check that all the options specified on the command line are either defined by SCons itself - or defined by &f-link-AddOption;. - - - If throw_exception is True, &f-ValidateOptions; will raise a - SConsBadOptionError - exception instead of printing an error message and exiting with an error status. - - - 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. + or defined by calls to &f-link-AddOption;. This function should only be called after the last &f-link-AddOption; call in your &SConscript; @@ -4408,17 +4398,44 @@ the tool object, previously it did not return 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;. + + 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. + If the optional throw_exception is True, &f-ValidateOptions; will raise a + SConsBadOptionError + exception. This would allow the calling + &SConscript; logic can catch that exception and handle invalid options itself. + Example: - + +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) - + + + + 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. + + +scons --compilers=mingw (the correct flag is --compiler) + + + 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. + + + -- cgit v0.12