Merge branch 'master' of github.com:SCons/scons

14 files changed, 248 insertions, 77 deletions

diff --git a/README-package.rst b/README-package.rst
new file mode 100755
index 000000000..605e5fe29
--- /dev/null
+++ b/README-package.rst
@@ -0,0 +1,134 @@
+SCons - a software construction tool
+####################################
+
+.. image:: https://img.shields.io/badge/IRC-scons-blue.svg
+   :target: http://webchat.freenode.net/?channels=%23scons&uio=d4
+   :alt: IRC
+
+.. image:: https://img.shields.io/sourceforge/dm/scons.svg
+   :target: https://sourceforge.net/projects/scons
+   :alt: Sourceforge Monthly Downloads
+
+.. image:: https://img.shields.io/sourceforge/dt/scons.svg
+   :target: https://sourceforge.net/projects/scons
+   :alt: Sourceforge Total Downloads
+
+.. image:: https://travis-ci.org/SCons/scons.svg?branch=master
+   :target: https://travis-ci.org/SCons/scons
+   :alt: Travis CI build status
+
+.. image:: https://ci.appveyor.com/api/projects/status/github/SCons/scons?svg=true&branch=master
+   :target: https://ci.appveyor.com/project/SCons/scons
+   :alt: AppVeyor CI build Status
+
+.. image:: https://codecov.io/gh/SCons/scons/branch/master/graph/badge.svg
+   :target: https://codecov.io/gh/SCons/scons
+   :alt: CodeCov Coverage Status
+
+About SCons
+-----------
+
+This is SCons, a tool for building software (and other files).  SCons is
+implemented in Python, and its "configuration files" are actually Python
+scripts, allowing you to use the full power of a real scripting language
+to solve build problems.  You do not, however, need to know Python to
+use SCons effectively.
+
+Documentation
+-------------
+
+Documentation for SCons is available at:
+
+        http://www.scons.org/documentation.html
+
+Requirements
+------------
+
+Running SCons requires Python 3.5 or higher. There should be no other
+dependencies or requirements to run SCons, although the pywin32 Python
+package is strongly recommended if running on Windows systems.
+
+
+By default, SCons knows how to search for available programming tools on
+various systems--see the SCons man page for details.  You may, of course,
+override the default SCons choices made by appropriate configuration of
+Environment construction variables.
+
+
+Licensing
+=========
+
+SCons is distributed under the MIT license, a full copy of which is available
+in the LICENSE file.
+
+
+Reporting Bugs
+==============
+
+The SCons project welcomes bug reports and feature requests.
+
+Please make sure you send email with the problem or feature request to
+the SCons users mailing list:
+
+        Join via: http://two.pairlist.net/mailman/listinfo/scons-users
+
+Or the SCons Discord server #scons-help channel
+
+        Server URL: https://discord.gg/bXVpWAy
+
+Once you have discussed your issue on the users mailing list and the
+community has confirmed that it is either a new bug or a duplicate of an
+existing bug, then please follow the instructions the community provides
+to file a new bug or to add yourself to the CC list for an existing bug
+
+You can explore the list of existing bugs, which may include workarounds
+for the problem you've run into on GitHub Issues:
+
+        https://github.com/SCons/scons/issues
+
+
+Mailing Lists
+=============
+
+An active mailing list for developers of SCons is available.  You may
+send questions or comments to the list at:
+
+        scons-dev@scons.org
+
+You may subscribe to the developer's mailing list using form on this page:
+
+        http://two.pairlist.net/mailman/listinfo/scons-dev
+
+Subscription to the developer's mailing list is by approval.  In practice, no
+one is refused list membership, but we reserve the right to limit membership
+in the future and/or weed out lurkers.
+
+There are other mailing lists available for SCons users, for notification of
+SCons code changes, and for notification of updated bug reports and project
+documents.  Please see our mailing lists page for details.
+
+
+Donations
+=========
+
+If you find SCons helpful, please consider making a donation (of cash,
+software, or hardware) to support continued work on the project.  Information
+is available at:
+
+    http://www.scons.org/donate.html
+
+or via GitHub Sponsors button on
+
+    https://github.com/scons/scons
+
+
+For More Information
+====================
+
+Check the SCons web site at:
+
+        http://www.scons.org/
+
+
+Copyright (c) 2001 - 2020 The SCons Foundation
+
diff --git a/SCons/Tool/msvc.xml b/SCons/Tool/msvc.xml
index 776c36157..2dec9c5b0 100644
--- a/SCons/Tool/msvc.xml
+++ b/SCons/Tool/msvc.xml
@@ -371,7 +371,7 @@ Valid values for Windows are
 <literal>7.1</literal>,
 <literal>7.0</literal>,
 and <literal>6.0</literal>.
-Versions ending in <literal>Exp</literal> refer to "Express" or 
+Versions ending in <literal>Exp</literal> refer to "Express" or
 "Express for Desktop" editions.
 </para>
 
@@ -381,17 +381,32 @@ Versions ending in <literal>Exp</literal> refer to "Express" or
 <cvar name="MSVC_USE_SCRIPT">
 <summary>
 <para>
-Use a batch script to set up Microsoft Visual Studio compiler
+Use a batch script to set up Microsoft Visual Studio compiler.
 </para>
 
 <para>
-&cv-MSVC_USE_SCRIPT; overrides &cv-MSVC_VERSION; and &cv-TARGET_ARCH;.
-If set to the name of a Visual Studio .bat file (e.g. vcvars.bat),
-SCons will run that bat file and extract the relevant variables from
-the result (typically %INCLUDE%, %LIB%, and %PATH%).  Setting
-MSVC_USE_SCRIPT to None bypasses the Visual Studio autodetection
-entirely; use this if you are running SCons in a Visual Studio cmd
-window and importing the shell's environment variables.
+If set to the name of a Visual Studio <filename>.bat</filename> file
+(e.g. <filename>vcvars.bat</filename>),
+&SCons; will run that batch file instead of the auto-detected one,
+and extract the relevant variables from the result (typically
+<envar>%INCLUDE%</envar>,
+<envar>%LIB%</envar>, and
+<envar>%PATH%</envar>) for supplying to the build.
+This can be useful to force the use of a compiler version that
+&SCons; does not detect.
+</para>
+
+<para>
+Setting
+&cv-MSVC_USE_SCRIPT; to <constant>None</constant> bypasses the
+Visual Studio autodetection entirely;
+use this if you are running SCons in a Visual Studio cmd
+window and importing the shell's environment variables - that
+is, if you are sure everything is set correctly already and
+you don't want &SCons; to change anything.
+</para>
+<para>
+&cv-MSVC_USE_SCRIPT; overrides &cv-link-MSVC_VERSION; and &cv-link-TARGET_ARCH;.
 </para>
 </summary>
 </cvar>
@@ -403,15 +418,15 @@ Sets the host architecture for Visual Studio compiler. If not set,
 default to the detected host architecture: note that this may depend
 on the python you are using.
 This variable must be passed as an argument to the Environment()
-constructor; setting it later has no effect. 
+constructor; setting it later has no effect.
 </para>
 
 <para>
-Valid values are the same as for &cv-TARGET_ARCH;.
+Valid values are the same as for &cv-link-TARGET_ARCH;.
 </para>
 
 <para>
-This is currently only used on Windows, but in the future it will be
+This is currently only used on Windows, but in the future it may be
 used on other OSes as well.
 </para>
 </summary>
@@ -421,31 +436,36 @@ used on other OSes as well.
 <para>
 Sets the target architecture for Visual Studio compiler (i.e. the arch
 of the binaries generated by the compiler). If not set, default to
-&cv-HOST_ARCH;, or, if that is unset, to the architecture of the
+&cv-link-HOST_ARCH;, or, if that is unset, to the architecture of the
 running machine's OS (note that the python build or architecture has no
 effect).
 This variable must be passed as an argument to the Environment()
-constructor; setting it later has no effect.  
+constructor; setting it later has no effect.
 This is currently only used on Windows, but in the future it will be
 used on other OSes as well.
-If this is set and MSVC_VERSION is not set, this will search for 
-all installed MSVC's that support the TARGET_ARCH, selecting the 
+If this is set and &cv-link-MSVC_VERSION; is not set, this will search for
+all installed MSVC's that support the &cv-TARGET_ARCH;, selecting the
 latest version for use.
 </para>
 
 <para>
-Valid values for Windows are
+On Windows, valid target values are
 <literal>x86</literal>,
 <literal>arm</literal>,
 <literal>i386</literal>
-(for 32 bits); 
+for 32-bit targets and
 <literal>amd64</literal>,
 <literal>arm64</literal>,
-<literal>emt64</literal>,
+<literal>em64t</literal>,
 <literal>x86_64</literal>
-(for 64 bits);
-and <literal>ia64</literal> (Itanium).
+and <literal>ia64</literal> (Itanium)
+for 64-bit targets.
+Note that not all target architectures are
+supported for all Visual Studio / MSVC versions
+check the relevant Microsoft documentation.
+</para>
 
+<para>
 For example, if you want to compile 64-bit binaries, you would set
 <literal>TARGET_ARCH='x86_64'</literal> in your SCons environment.
 </para>
@@ -463,7 +483,7 @@ If &cv-MSVC_UWP_APP; is set, the Visual Studio environment will be set up to poi
 to the Windows Store compatible libraries and Visual Studio runtimes. In doing so,
 any libraries that are built will be able to be used in a UWP App and published
 to the Windows Store.
-This flag will only have an effect with Visual Studio 2015+.
+This flag will only have an effect with Visual Studio 2015 or later.
 This variable must be passed as an argument to the Environment()
 constructor; setting it later has no effect.
 </para>
@@ -478,7 +498,7 @@ Valid values are '1' or '0'
 <cvar name="VSWHERE">
 <summary>
 <para>
-Specify the location of <filename>vswhere.exe</filename>. 
+Specify the location of <filename>vswhere.exe</filename>.
 </para>
 
 <para>
diff --git a/SCons/__init__.py b/SCons/__init__.py
index 8520fe0a4..af01bf783 100644
--- a/SCons/__init__.py
+++ b/SCons/__init__.py
@@ -1,9 +1,9 @@
-__version__="3.9.9a996"
+__version__="3.9.9a998"
 __copyright__="Copyright (c) 2001 - 2020 The SCons Foundation"
 __developer__="bdbaddog"
-__date__="2020-06-30 23:00:35"
+__date__="2020-07-04 19:53:36"
 __buildsys__="ProDog2020"
-__revision__="8e18d0c324c2605936198e64d349c89082b1463d"
-__build__="8e18d0c324c2605936198e64d349c89082b1463d"
+__revision__="ecb9741551fa0276fccd7d8d6f1df03a4e338082"
+__build__="ecb9741551fa0276fccd7d8d6f1df03a4e338082"
 # make sure compatibility is always in place
 import SCons.compat # noqa
\ No newline at end of file
diff --git a/SConstruct b/SConstruct
index a143c9306..0ced773fb 100644
--- a/SConstruct
+++ b/SConstruct
@@ -37,7 +37,7 @@ month_year = strftime('%B %Y')
 
 
 project = 'scons'
-default_version = '3.9.9a996'
+default_version = '3.9.9a998'
 copyright = "Copyright (c) %s The SCons Foundation" % copyright_years
 
 #
@@ -200,8 +200,8 @@ env.Command('$DISTDIR/SCons-${VERSION}-py3-none-any.whl', ['setup.cfg', 'setup.p
 
 env.Command('$DISTDIR/SCons-${VERSION}.zip', ['setup.cfg', 'setup.py', 'SCons/__init__.py'],
             '$PYTHON setup.py sdist --format=zip')
-env.Command('$DISTDIR/SCons-${VERSION}.tar.bz2', ['setup.cfg', 'setup.py', 'SCons/__init__.py'],
-            '$PYTHON setup.py sdist --format=bztar')
+env.Command('$DISTDIR/SCons-${VERSION}.tar.gz', ['setup.cfg', 'setup.py', 'SCons/__init__.py'],
+            '$PYTHON setup.py sdist --format=gztar')
 
 # TODO add auto copyright date to README.rst, LICENSE
 # TODO build API DOCS
diff --git a/bin/SConsDoc.py b/bin/SConsDoc.py
index a2daa5501..ba9c923ce 100644
--- a/bin/SConsDoc.py
+++ b/bin/SConsDoc.py
@@ -571,12 +571,12 @@ class SConsDocHandler:
                                xpath_context, nsmap, include_entities)
 
     def parseContent(self, content, include_entities=True):
-        """ Parses the given content as XML file. This method
-            is used when we generate the basic lists of entities
-            for the builders, tools and functions.
-            So we usually don't bother about namespaces and resolving
-            entities here...this is handled in parseXmlFile below
-            (step 2 of the overall process).
+        """Parse the given content as XML.
+
+        This method is used when we generate the basic lists of entities
+        for the builders, tools and functions.  So we usually don't
+        bother about namespaces and resolving entities here...
+        this is handled in parseXmlFile below (step 2 of the overall process).
         """
         # Create doctree
         t = SConsDocTree()
diff --git a/bin/docs-create-example-outputs.py b/bin/docs-create-example-outputs.py
index 012443533..e5d40ce4c 100644
--- a/bin/docs-create-example-outputs.py
+++ b/bin/docs-create-example-outputs.py
@@ -9,10 +9,13 @@ import SConsExamples
 
 if __name__ == "__main__":
     print("Checking whether all example names are unique...")
-    if SConsExamples.exampleNamesAreUnique(os.path.join('doc','user')):
+    if SConsExamples.exampleNamesAreUnique(os.path.join('doc', 'user')):
         print("OK")
     else:
-        print("Not all example names and suffixes are unique! Please correct the errors listed above and try again.")
+        print(
+            "Not all example names and suffixes are unique! "
+            "Please correct the errors listed above and try again."
+        )
         sys.exit(1)
 
-    SConsExamples.createAllExampleOutputs(os.path.join('doc','user'))
+    SConsExamples.createAllExampleOutputs(os.path.join('doc', 'user'))
diff --git a/bin/docs-update-generated.py b/bin/docs-update-generated.py
index 36878965e..bb5371f03 100644
--- a/bin/docs-update-generated.py
+++ b/bin/docs-update-generated.py
@@ -13,18 +13,22 @@ import subprocess
 import SConsDoc
 
 # Directory where all generated files are stored
-gen_folder = os.path.join('doc','generated')
+gen_folder = os.path.join('doc', 'generated')
 
 def argpair(key):
     """ Return the argument pair *.gen,*.mod for the given key. """
-    arg = '%s,%s' % (os.path.join(gen_folder, '%s.gen' % key),
-                     os.path.join(gen_folder, '%s.mod' % key))
-    
+    arg = '%s,%s' % (
+        os.path.join(gen_folder, '%s.gen' % key),
+        os.path.join(gen_folder, '%s.mod' % key),
+    )
+
     return arg
 
 def generate_all():
-    """ Scan for XML files in the SCons directory and call scons-proc.py
-        to generate the *.gen/*.mod files from it.
+    """Generate the entity files.
+
+    Scan for XML files in the SCons directory and call scons-proc.py
+    to generate the *.gen/*.mod files from it.
     """
     flist = []
     for path, dirs, files in os.walk('SCons'):
@@ -36,12 +40,12 @@ def generate_all():
 
     if flist:
         # Does the destination folder exist
-        if not os.path.isdir(gen_folder):
-            try:
-                os.makedirs(gen_folder)
-            except:
-                print("Couldn't create destination folder %s! Exiting..." % gen_folder)
-                return
+        try:
+            os.makedirs(gen_folder, exist_ok=True)
+        except Exception:
+            print("Couldn't create destination folder %s! Exiting..." % gen_folder, file=sys.stdout)
+            return False
+
         # Call scons-proc.py
         cp = subprocess.run(
             [
@@ -55,10 +59,11 @@ def generate_all():
             shell=False,
         )
 
-        # No-op: scons-proc doesn't actually set an exit code at the moment.
         if cp.returncode:
             print("Generation failed", file=sys.stderr)
+            return False
     
     
 if __name__ == "__main__":
-    generate_all()
+    if not generate_all():
+        sys.exit(1)
diff --git a/bin/docs-validate.py b/bin/docs-validate.py
index c4dd3b7f3..6d8fd770a 100644
--- a/bin/docs-validate.py
+++ b/bin/docs-validate.py
@@ -7,20 +7,24 @@ import sys,os
 import SConsDoc
 
 if __name__ == "__main__":
-    if len(sys.argv)>1:
+    if len(sys.argv) > 1:
         if SConsDoc.validate_all_xml((sys.argv[1],)):
             print("OK")
         else:
             print("Validation failed! Please correct the errors above and try again.")
+            sys.exit(1)
     else:
-        if SConsDoc.validate_all_xml(['src',
-                                      os.path.join('doc','design'),
-                                      os.path.join('doc','developer'),
-                                      os.path.join('doc','man'),
-                                      os.path.join('doc','python10'),
-                                      os.path.join('doc','reference'),
-                                      os.path.join('doc','user')
-                                      ]):
+        if SConsDoc.validate_all_xml(
+            [
+                'SCons',
+                os.path.join('doc', 'design'),
+                os.path.join('doc', 'developer'),
+                os.path.join('doc', 'man'),
+                os.path.join('doc', 'python10'),
+                os.path.join('doc', 'reference'),
+                os.path.join('doc', 'user'),
+            ]
+        ):
             print("OK")
         else:
             print("Validation failed! Please correct the errors above and try again.")
diff --git a/bin/scons-proc.py b/bin/scons-proc.py
index fb9e6df3c..799b12a14 100644
--- a/bin/scons-proc.py
+++ b/bin/scons-proc.py
@@ -61,9 +61,10 @@ def parse_docs(args, include_entities=True):
         if include_entities:
             try:
                 h.parseXmlFile(f)
-            except:
-                sys.stderr.write("error in %s\n" % f)
-                raise
+            except Exception as e:
+                print("error parsing %s\n" % f, file=sys.stderr)
+                print(str(e), file=sys.stderr)
+                sys.exit(1)
         else:
             # mode we read (text/bytes) has to match handling in SConsDoc
             with open(f, 'r') as fp:
@@ -71,9 +72,10 @@ def parse_docs(args, include_entities=True):
             if content:
                 try:
                     h.parseContent(content, include_entities)
-                except:
-                    sys.stderr.write("error in %s\n" % f)
-                    raise
+                except Exception as e:
+                    print("error parsing %s\n" % f, file=sys.stderr)
+                    print(str(e), file=sys.stderr)
+                    sys.exit(1)
     return h
 
 Warning = """\
@@ -408,6 +410,7 @@ if SConsDoc.validate_all_xml(['SCons']):
     print("OK")
 else:
     print("Validation failed! Please correct the errors above and try again.")
+    sys.exit(1)
 
 # Step 3: Creating actual documentation snippets, using the
 #         fully resolved and updated entities from the *.mod files.
diff --git a/doc/generated/examples/caching_ex-random_1.xml b/doc/generated/examples/caching_ex-random_1.xml
index 5db645909..cd09c1007 100644
--- a/doc/generated/examples/caching_ex-random_1.xml
+++ b/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 f2.o -c f2.c
 cc -o f3.o -c f3.c
-cc -o f4.o -c f4.c
-cc -o f5.o -c f5.c
 cc -o f1.o -c f1.c
+cc -o f5.o -c f5.c
+cc -o f2.o -c f2.c
+cc -o f4.o -c f4.c
 cc -o prog f1.o f2.o f3.o f4.o f5.o
 </screen>
diff --git a/doc/generated/examples/troubleshoot_Dump_2.xml b/doc/generated/examples/troubleshoot_Dump_2.xml
index 0eb0f98e8..508082269 100644
--- a/doc/generated/examples/troubleshoot_Dump_2.xml
+++ b/doc/generated/examples/troubleshoot_Dump_2.xml
@@ -91,7 +91,7 @@ scons: Reading SConscript files ...
   'SHCXXCOM': '${TEMPFILE("$SHCXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES '
               '$SHCXXFLAGS $SHCCFLAGS $_CCCOMCOM","$SHCXXCOMSTR")}',
   'SHCXXFLAGS': ['$CXXFLAGS'],
-  'SHELL': None,
+  'SHELL': 'command',
   'SHLIBPREFIX': '',
   'SHLIBSUFFIX': '.dll',
   'SHOBJPREFIX': '$OBJPREFIX',
diff --git a/doc/generated/examples/troubleshoot_explain1_3.xml b/doc/generated/examples/troubleshoot_explain1_3.xml
index 98a2d1307..4e53d5e67 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 "/home/mats/github/scons/scripts/scons.py", line 96, in &lt;module&gt;
+File "/Users/bdbaddog/devel/scons/git/scons-bugfixes-2/scripts/scons.py", line 96, in &lt;module&gt;
 </screen>
diff --git a/doc/man/sconsign.xml b/doc/man/sconsign.xml
index 93842ad43..af4ec918d 100644
--- a/doc/man/sconsign.xml
+++ b/doc/man/sconsign.xml
@@ -306,8 +306,8 @@ for all entries or the specified entries.</para>
 </refsect1>
 
 <refsect1 id='see_also'>
-<para>
 <title>SEE ALSO</title>
+<para>
 <command>scons</command>,
 the SCons User Guide at
 <ulink url="https://scons.org/doc/production/HTML/scons-user.html"/>,
diff --git a/setup.cfg b/setup.cfg
index c3c396e28..1577010a5 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,10 +1,9 @@
 [metadata]
 name = SCons
-;version=3.9.9a993
 license = MIT
 author = William Deegan
 author_email =bill@baddogconsulting.com
-long_description = file: README.rst
+long_description = file: README-package.rst
 long_description_content_type = text/x-rst
 description = Open Source next-generation build tool.
 group = Development/Tools
@@ -41,7 +40,10 @@ classifiers =
 [options]
 zip_safe = False
 python_requires = >=3.5
-install_requires = setuptools
+install_requires =
+    setuptools
+    pywin32 >= 1.0;platform_system=="Windows"
+
 setup_requires = setuptools
 include_package_data = True
 packages = find: