Added docs

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.
 </summary>
 </scons_function>
 
+<scons_function name="DebugOptions">
+<arguments signature="global">
+([json])
+</arguments>
+<summary>
+<para>
+Allows setting options for SCons debug options. Currently the only supported value is
+  <emphasis>json</emphasis> which sets the path to the json file created when
+  <literal>--debug=json</literal> is set.
+</para>
+  <example_commands>
+DebugOptions(json='#/build/output/scons_stats.json')
+</example_commands>
+</summary>
+</scons_function>
+
+
 <scons_function name="GetBuildFailures">
 <arguments signature="global">
 ()
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 @@
 <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 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 &lt;module&gt;
+File "/Users/bdbaddog/devel/scons/git/scons-2/scripts/scons.py", line 97, in &lt;module&gt;
 </screen>
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
 <parameter>target</parameter>
 has been built.
-The specified action(s) may be
+<parameter>action</parameter> 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.
 </para>
@@ -261,6 +261,13 @@ the action may be called multiple times,
 once after each action that generates
 one or more targets in the list.
 </para>
+
+<example_commands>
+foo = Program('foo.c')
+# remove execute permission from binary:
+AddPostAction(foo, Chmod('$TARGET', "a-x"))
+</example_commands>
+
 </listitem>
   </varlistentry>
   <varlistentry id="f-AddPreAction">
@@ -273,9 +280,9 @@ to be performed
 before the specified
 <parameter>target</parameter>
 is built.
-The specified action(s) may be
+<parameter>action</parameter> 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.
 </para>
@@ -318,20 +325,34 @@ file into an object file.
 </listitem>
   </varlistentry>
   <varlistentry id="f-Alias">
-    <term><function>Alias</function>(<parameter>alias, [targets, [action]]</parameter>)</term>
-    <term><replaceable>env</replaceable>.<methodname>Alias</methodname>(<parameter>alias, [targets, [action]]</parameter>)</term>
+    <term><function>Alias</function>(<parameter>alias, [source, [action]]</parameter>)</term>
+    <term><replaceable>env</replaceable>.<methodname>Alias</methodname>(<parameter>alias, [source, [action]]</parameter>)</term>
     <listitem><para>
-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 <parameter>source</parameter>
+parameter.
+<parameter>alias</parameter> and
+<parameter>source</parameter>
+may each be a string or Node object,
+or a list of strings or Node objects;
+if Nodes are used for
+<parameter>alias</parameter>
+they must be Alias nodes.
+The optional
 <parameter>action</parameter>
-(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,
+</para>
+
+<para>
+Returns a list of Alias Node objects representing the alias(es),
+which exist outside of any physical file system.
+</para>
+
+<para>
+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 <literal>=</literal> to specify a valued macro.</para>
 </listitem>
 <listitem>
-<para>A tuple is treated as a valued macro. 
+<para>A tuple is treated as a valued macro.
 Use the value <constant>None</constant> if the macro should not have a value.
 It is an error to supply more than two elements in such a tuple.</para>
 </listitem>
@@ -1117,13 +1138,25 @@ so you normally don't need to create directories by hand.
     <term><function>Configure</function>(<parameter>env, [custom_tests, conf_dir, log_file, config_h]</parameter>)</term>
     <term><replaceable>env</replaceable>.<methodname>Configure</methodname>(<parameter>[custom_tests, conf_dir, log_file, config_h]</parameter>)</term>
     <listitem><para>
-Creates a Configure object for integrated
-functionality similar to GNU autoconf.
+Creates a &Configure; object for integrated
+functionality similar to GNU <command>autoconf</command>.
 See the manpage section "Configure Contexts"
 for a complete explanation of the arguments and behavior.
 </para>
 </listitem>
   </varlistentry>
+  <varlistentry id="f-DebugOptions">
+    <term><function>DebugOptions</function>(<parameter>[json]</parameter>)</term>
+    <listitem><para>
+Allows setting options for SCons debug options. Currently the only supported value is
+  <emphasis>json</emphasis> which sets the path to the json file created when
+  <literal>--debug=json</literal> is set.
+</para>
+  <example_commands>
+DebugOptions(json='#/build/output/scons_stats.json')
+</example_commands>
+</listitem>
+  </varlistentry>
   <varlistentry id="f-Decider">
     <term><function>Decider</function>(<parameter>function</parameter>)</term>
     <term><replaceable>env</replaceable>.<methodname>Decider</methodname>(<parameter>function</parameter>)</term>
@@ -1141,50 +1174,24 @@ that will be applied:
 <para>
 <variablelist>
 <varlistentry>
-<term><literal>"timestamp-newer"</literal></term>
-<listitem>
-<para>
-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
-<literal>make</literal>
-can be used a synonym for
-<literal>timestamp-newer</literal>.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><literal>"timestamp-match"</literal></term>
-<listitem>
-<para>
-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
-<emphasis>earlier</emphasis>
-timestamp, such as can happen when restoring files from backup archives.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
 <term><literal>"content"</literal></term>
 <listitem>
 <para>
 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.
-<literal>MD5</literal>
-can be used as a synonym for
-<literal>content</literal>, but it is deprecated.
+<literal>content</literal> is the default decider.
+</para>
+<para>
+<emphasis>Changed in version 4.1:</emphasis>
+The decider was renamed to <literal>content</literal>
+since the hash function is now selectable.
+The former name, <literal>MD5</literal>,
+can still be used as a synonym, but is deprecated.
 </para>
 </listitem>
 </varlistentry>
@@ -1215,9 +1222,44 @@ that runs a build,
 updates a file,
 and runs the build again,
 all within a single second.
-<literal>MD5-timestamp</literal>
-can be used as a synonym for
-<literal>content-timestamp</literal>, but it is deprecated.
+</para>
+<para>
+<emphasis>Changed in version 4.1:</emphasis>
+The decider was renamed to <literal>content-timestamp</literal>
+since the hash function is now selectable.
+The former name, <literal>MD5-timestamp</literal>,
+can still be used as a synonym, but is deprecated.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>"timestamp-newer"</literal></term>
+<listitem>
+<para>
+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
+<literal>make</literal>
+can be used a synonym for
+<literal>timestamp-newer</literal>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>"timestamp-match"</literal></term>
+<listitem>
+<para>
+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
+<emphasis>earlier</emphasis>
+timestamp, such as can happen when restoring files from backup archives.
 </para>
 </listitem>
 </varlistentry>
@@ -3973,7 +4015,7 @@ Sets &scons; option variable <parameter>name</parameter>
 to <parameter>value</parameter>.
 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
   <varlistentry id="f-ValidateOptions">
     <term><function>ValidateOptions</function>(<parameter>[throw_exception=False]</parameter>)</term>
     <listitem><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>
+        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.
+      </para>
+
+      <para>
+        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;.
+      </para>
+
+      <para>
+        If there are any unknown command line options, &f-ValidateOptions;
+        prints an error message and exits with an error exit status.
+        If the optional <parameter>throw_exception</parameter> argument is
+        <literal>True</literal> (default is <literal>False</literal>),
+        a <exceptionname>SConsBadOptionError</exceptionname> 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).
+      </para>
+
+      <para>
+        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:
+      </para>
+
+      <screen>
+$ <userinput>scons --compilers=mingw</userinput>  # the correct flag is --compiler
+      </screen>
+
+      <para>
+        Here &SCons; could go off and run a bunch of configure steps with
+        the default value of <literal>--compiler</literal>, 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:
+      </para>
+
+      <programlisting language="python">
+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)
-            </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>
-            <para>
-                <emphasis>New in version 4.5.0</emphasis>
-            </para>
-        </listitem>
+      </programlisting>
+
+      <para><emphasis>New in version 4.5.0</emphasis></para>
+
+    </listitem>
   </varlistentry>
   <varlistentry id="f-Value">
     <term><function>Value</function>(<parameter>value, [built_value], [name]</parameter>)</term>
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.
 <!ENTITY f-Clone "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Clone</function>">
 <!ENTITY f-Command "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Command</function>">
 <!ENTITY f-Configure "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Configure</function>">
+<!ENTITY f-DebugOptions "<function xmlns='http://www.scons.org/dbxsd/v1.0'>DebugOptions</function>">
 <!ENTITY f-Decider "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Decider</function>">
 <!ENTITY f-Default "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Default</function>">
 <!ENTITY f-DefaultEnvironment "<function xmlns='http://www.scons.org/dbxsd/v1.0'>DefaultEnvironment</function>">
@@ -106,6 +107,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY f-env-Clone "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Clone</function>">
 <!ENTITY f-env-Command "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Command</function>">
 <!ENTITY f-env-Configure "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Configure</function>">
+<!ENTITY f-env-DebugOptions "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.DebugOptions</function>">
 <!ENTITY f-env-Decider "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Decider</function>">
 <!ENTITY f-env-Default "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Default</function>">
 <!ENTITY f-env-DefaultEnvironment "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.DefaultEnvironment</function>">
@@ -193,6 +195,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY f-link-Clone "<link linkend='f-Clone' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Clone</function></link>">
 <!ENTITY f-link-Command "<link linkend='f-Command' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Command</function></link>">
 <!ENTITY f-link-Configure "<link linkend='f-Configure' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Configure</function></link>">
+<!ENTITY f-link-DebugOptions "<link linkend='f-DebugOptions' xmlns='http://www.scons.org/dbxsd/v1.0'><function>DebugOptions</function></link>">
 <!ENTITY f-link-Decider "<link linkend='f-Decider' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Decider</function></link>">
 <!ENTITY f-link-Default "<link linkend='f-Default' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Default</function></link>">
 <!ENTITY f-link-DefaultEnvironment "<link linkend='f-DefaultEnvironment' xmlns='http://www.scons.org/dbxsd/v1.0'><function>DefaultEnvironment</function></link>">
@@ -274,6 +277,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY f-link-env-Clone "<link linkend='f-Clone' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Clone</function></link>">
 <!ENTITY f-link-env-Command "<link linkend='f-Command' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Command</function></link>">
 <!ENTITY f-link-env-Configure "<link linkend='f-Configure' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Configure</function></link>">
+<!ENTITY f-link-env-DebugOptions "<link linkend='f-DebugOptions' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.DebugOptions</function></link>">
 <!ENTITY f-link-env-Decider "<link linkend='f-Decider' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Decider</function></link>">
 <!ENTITY f-link-env-Default "<link linkend='f-Default' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Default</function></link>">
 <!ENTITY f-link-env-DefaultEnvironment "<link linkend='f-DefaultEnvironment' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.DefaultEnvironment</function></link>">
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 @@ $ <userinput>scons --debug=includes foo.o</userinput>
 <varlistentry>
   <term><emphasis role="bold">json</emphasis></term>
   <listitem>
-<para>Write info for any of the following debug options if they are enabled: <emphasis role="bold">memory</emphasis>,
+<para>Write info to a JSON file for any of the following debug options if they are enabled: <emphasis>memory</emphasis>,
     <emphasis>count</emphasis>, <emphasis>time</emphasis>, <emphasis>action-timestamps</emphasis> </para>
+    <para>The default output file is in the top level directory named <literal>scons_stats.json</literal></para>
+    <para>The file name/path can be modified by using <literal>DebugOptions(json='path/to/file.json')</literal></para>
 
 <screen>
 $ <userinput>scons --debug=memory,json foo.o</userinput>