From 0467f15ea25a719fa45ee86d74a1b1657a357105 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Mon, 5 Jun 2023 10:43:47 -0700 Subject: Added docs --- SCons/Script/Main.xml | 17 ++ SCons/Util/stats.py | 2 +- doc/generated/examples/caching_ex-random_1.xml | 2 +- doc/generated/examples/troubleshoot_explain1_3.xml | 2 +- .../examples/troubleshoot_stacktrace_2.xml | 3 +- doc/generated/functions.gen | 269 +++++++++++++-------- doc/generated/functions.mod | 4 + doc/man/scons.xml | 4 +- 8 files changed, 193 insertions(+), 110 deletions(-) diff --git a/SCons/Script/Main.xml b/SCons/Script/Main.xml index 379d534..9248668 100644 --- a/SCons/Script/Main.xml +++ b/SCons/Script/Main.xml @@ -183,6 +183,23 @@ Future versions of &SCons; will likely forbid such usage. + + +([json]) + + + +Allows setting options for SCons debug options. Currently the only supported value is + json which sets the path to the json file created when + --debug=json is set. + + +DebugOptions(json='#/build/output/scons_stats.json') + + + + + () diff --git a/SCons/Util/stats.py b/SCons/Util/stats.py index 911910b..58fa5dd 100644 --- a/SCons/Util/stats.py +++ b/SCons/Util/stats.py @@ -160,7 +160,7 @@ def WriteJsonFile(): from SCons.Script import BUILD_TARGETS, COMMAND_LINE_TARGETS, ARGUMENTS, ARGLIST - print(f"DUMPING JSON FILE: {JSON_OUTPUT_FILE}") + # print(f"DUMPING JSON FILE: {JSON_OUTPUT_FILE}") json_structure = {} if COUNT_STATS.enabled: json_structure['Object counts'] = {} diff --git a/doc/generated/examples/caching_ex-random_1.xml b/doc/generated/examples/caching_ex-random_1.xml index 4773380..422f37d 100644 --- a/doc/generated/examples/caching_ex-random_1.xml +++ b/doc/generated/examples/caching_ex-random_1.xml @@ -1,7 +1,7 @@ % scons -Q -cc -o f1.o -c f1.c cc -o f4.o -c f4.c cc -o f2.o -c f2.c +cc -o f1.o -c f1.c cc -o f5.o -c f5.c cc -o f3.o -c f3.c cc -o prog f1.o f2.o f3.o f4.o f5.o diff --git a/doc/generated/examples/troubleshoot_explain1_3.xml b/doc/generated/examples/troubleshoot_explain1_3.xml index e658d89..a0aec9f 100644 --- a/doc/generated/examples/troubleshoot_explain1_3.xml +++ b/doc/generated/examples/troubleshoot_explain1_3.xml @@ -2,5 +2,5 @@ cp file.in file.oout scons: warning: Cannot find target file.out after building -File "/Users/bdbaddog/devel/scons/git/as_scons/scripts/scons.py", line 97, in <module> +File "/Users/bdbaddog/devel/scons/git/scons-2/scripts/scons.py", line 97, in <module> diff --git a/doc/generated/examples/troubleshoot_stacktrace_2.xml b/doc/generated/examples/troubleshoot_stacktrace_2.xml index 79234f2..668e67f 100644 --- a/doc/generated/examples/troubleshoot_stacktrace_2.xml +++ b/doc/generated/examples/troubleshoot_stacktrace_2.xml @@ -3,8 +3,9 @@ scons: *** [prog.o] Source `prog.c' not found, needed by target `prog.o'. scons: internal stack trace: File "SCons/Taskmaster/Job.py", line 219, in start task.prepare() - File "SCons/Script/Main.py", line 180, in prepare + File "SCons/Script/Main.py", line 201, in prepare return SCons.Taskmaster.OutOfDateTask.prepare(self) + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "SCons/Taskmaster/__init__.py", line 195, in prepare executor.prepare() File "SCons/Executor.py", line 418, in prepare diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen index 5a74fc6..90d263d 100644 --- a/doc/generated/functions.gen +++ b/doc/generated/functions.gen @@ -248,9 +248,9 @@ to be performed after the specified target has been built. -The specified action(s) may be +action may be an Action object, or anything that -can be converted into an Action object +can be converted into an Action object. See the manpage section "Action Objects" for a complete explanation. @@ -261,6 +261,13 @@ the action may be called multiple times, once after each action that generates one or more targets in the list. + + +foo = Program('foo.c') +# remove execute permission from binary: +AddPostAction(foo, Chmod('$TARGET', "a-x")) + + @@ -273,9 +280,9 @@ to be performed before the specified target is built. -The specified action(s) may be +action may be an Action object, or anything that -can be converted into an Action object +can be converted into an Action object. See the manpage section "Action Objects" for a complete explanation. @@ -318,20 +325,34 @@ file into an object file. - Alias(alias, [targets, [action]]) - env.Alias(alias, [targets, [action]]) + Alias(alias, [source, [action]]) + env.Alias(alias, [source, [action]]) -Creates one or more phony targets that -expand to one or more other targets. -An optional +Creates a phony target (or targets) that +can be used as references to zero or more other targets, +as specified by the optional source +parameter. +alias and +source +may each be a string or Node object, +or a list of strings or Node objects; +if Nodes are used for +alias +they must be Alias nodes. +The optional action -(command) -or list of actions -can be specified that will be executed +parameter specifies an action or list of actions +that will be executed whenever the any of the alias targets are out-of-date. -Returns the Node object representing the alias, -which exists outside of any file system. -This Node object, or the alias name, + + + +Returns a list of Alias Node objects representing the alias(es), +which exist outside of any physical file system. + + + +The alias name, or an Alias Node object, may be used as a dependency of any other target, including another alias. &f-Alias; @@ -519,7 +540,7 @@ giving an easy way to enter multiple macros in one addition. Use an = to specify a valued macro. -A tuple is treated as a valued macro. +A tuple is treated as a valued macro. Use the value None if the macro should not have a value. It is an error to supply more than two elements in such a tuple. @@ -1117,13 +1138,25 @@ so you normally don't need to create directories by hand. Configure(env, [custom_tests, conf_dir, log_file, config_h]) env.Configure([custom_tests, conf_dir, log_file, config_h]) -Creates a Configure object for integrated -functionality similar to GNU autoconf. +Creates a &Configure; object for integrated +functionality similar to GNU autoconf. See the manpage section "Configure Contexts" for a complete explanation of the arguments and behavior. + + DebugOptions([json]) + +Allows setting options for SCons debug options. Currently the only supported value is + json which sets the path to the json file created when + --debug=json is set. + + +DebugOptions(json='#/build/output/scons_stats.json') + + + Decider(function) env.Decider(function) @@ -1141,50 +1174,24 @@ that will be applied: -"timestamp-newer" - - -Specifies that a target shall be considered out of date and rebuilt -if the dependency's timestamp is newer than the target file's timestamp. -This is the behavior of the classic Make utility, -and -make -can be used a synonym for -timestamp-newer. - - - - -"timestamp-match" - - -Specifies that a target shall be considered out of date and rebuilt -if the dependency's timestamp is different than the -timestamp recorded the last time the target was built. -This provides behavior very similar to the classic Make utility -(in particular, files are not opened up so that their -contents can be checksummed) -except that the target will also be rebuilt if a -dependency file has been restored to a version with an -earlier -timestamp, such as can happen when restoring files from backup archives. - - - - "content" Specifies that a target shall be considered out of date and rebuilt if the dependency's content has changed since the last time the target was built, -as determined be performing an checksum -on the dependency's contents +as determined by performing a checksum +on the dependency's contents using the selected hash function, and comparing it to the checksum recorded the last time the target was built. -MD5 -can be used as a synonym for -content, but it is deprecated. +content is the default decider. + + +Changed in version 4.1: +The decider was renamed to content +since the hash function is now selectable. +The former name, MD5, +can still be used as a synonym, but is deprecated. @@ -1215,9 +1222,44 @@ that runs a build, updates a file, and runs the build again, all within a single second. -MD5-timestamp -can be used as a synonym for -content-timestamp, but it is deprecated. + + +Changed in version 4.1: +The decider was renamed to content-timestamp +since the hash function is now selectable. +The former name, MD5-timestamp, +can still be used as a synonym, but is deprecated. + + + + +"timestamp-newer" + + +Specifies that a target shall be considered out of date and rebuilt +if the dependency's timestamp is newer than the target file's timestamp. +This is the behavior of the classic Make utility, +and +make +can be used a synonym for +timestamp-newer. + + + + +"timestamp-match" + + +Specifies that a target shall be considered out of date and rebuilt +if the dependency's timestamp is different than the +timestamp recorded the last time the target was built. +This provides behavior very similar to the classic Make utility +(in particular, files are not opened up so that their +contents can be checksummed) +except that the target will also be rebuilt if a +dependency file has been restored to a version with an +earlier +timestamp, such as can happen when restoring files from backup archives. @@ -3973,7 +4015,7 @@ Sets &scons; option variable name to value. These options are all also settable via command-line options but the variable name -may differ from the command-line option name - +may differ from the command-line option name - see the table for correspondences. A value set via command-line option will take precedence over one set with &f-SetOption;, which @@ -4481,57 +4523,74 @@ gltool(env) # adds 'opengl' to the TOOLS variable ValidateOptions([throw_exception=False]) - Check that all the options specified on the command line are either defined by SCons itself - or defined by calls to &f-link-AddOption;. - - - This function should only be called after the last &f-link-AddOption; call in your &SConscript; - logic. - - - 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: - - - + Check that all the options specified on the command line are either + &SCons; built-in options or defined via calls to &f-link-AddOption;. + &SCons; will eventually fail on unknown options anyway, but calling + this function allows the build to "fail fast" before executing + expensive logic later in the build. + + + + This function should only be called after the last &f-AddOption; + call in your &SConscript; logic. + Be aware that some tools call &f-AddOption;, if you are getting + error messages for arguments that they add, you will need to ensure + that those tools are loaded before calling &f-ValidateOptions;. + + + + If there are any unknown command line options, &f-ValidateOptions; + prints an error message and exits with an error exit status. + If the optional throw_exception argument is + True (default is False), + a SConsBadOptionError is raised, + giving an opportunity for the &SConscript; logic to catch that + exception and handle invalid options appropriately. Note that + this exception name needs to be imported (see the example below). + + + + A common build problem is typos (or thinkos) - a user enters an option + that is just a little off the expected value, or perhaps a different + word with a similar meaning. It may be useful to abort the build + before going too far down the wrong path. For example: + + + +$ scons --compilers=mingw # the correct flag is --compiler + + + + Here &SCons; could go off and run a bunch of configure steps with + the default value of --compiler, since the + incorrect command line did not actually supply a value to it, + costing developer time to track down why the configure logic + made the "wrong" choices. This example shows catching this: + + + +from SCons.Script.SConsOptions import SConsBadOptionError + +AddOption( + '--compiler', + dest='compiler', + action='store', + default='gcc', + type='string', +) + +# ... other SConscript logic ... + 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) + print(f"ValidateOptions detects a fail: ", 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. - - - New in version 4.5.0 - - + + + New in version 4.5.0 + + Value(value, [built_value], [name]) diff --git a/doc/generated/functions.mod b/doc/generated/functions.mod index 34424a5..7273aab 100644 --- a/doc/generated/functions.mod +++ b/doc/generated/functions.mod @@ -25,6 +25,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. Clone"> Command"> Configure"> +DebugOptions"> Decider"> Default"> DefaultEnvironment"> @@ -106,6 +107,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. env.Clone"> env.Command"> env.Configure"> +env.DebugOptions"> env.Decider"> env.Default"> env.DefaultEnvironment"> @@ -193,6 +195,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. Clone"> Command"> Configure"> +DebugOptions"> Decider"> Default"> DefaultEnvironment"> @@ -274,6 +277,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. env.Clone"> env.Command"> env.Configure"> +env.DebugOptions"> env.Decider"> env.Default"> env.DefaultEnvironment"> diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 7579ce2..dd70c21 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -932,8 +932,10 @@ $ scons --debug=includes foo.o json -Write info for any of the following debug options if they are enabled: memory, +Write info to a JSON file for any of the following debug options if they are enabled: memory, count, time, action-timestamps + The default output file is in the top level directory named scons_stats.json + The file name/path can be modified by using DebugOptions(json='path/to/file.json') $ scons --debug=memory,json foo.o -- cgit v0.12