[PR 3462] env-var-cache: fix exception to be 2.7 compatible

msvc env-var cache-read function use 'except IOError'
since 'FileNotFoundError' did not exist on Py2.7/win32.

try to handle error if caceh write fails.

add SCONS_CACHE_MSVC_CONFIG to manpage.

SCONS_CACHE_MSVC_CONFIG can take a pathname to specify
the cache file to use, or it can use the default.

slightly simplified logging setup - logging is stdlib since
py2.3, no need for try block on import.

Signed-off-by: Mats Wichmann <mats@linux.com>

3 files changed, 67 insertions, 37 deletions

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 9065f25..c406b76 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -7189,22 +7189,45 @@ env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
 </refsect1>
 
 <refsect1 id='environment'><title>ENVIRONMENT</title>
+
+<para>In general, &scons; is not controlled by environment
+variables set shell used to invoke it, leaving it
+up to the SConscript file author to import those if desired.
+However the following variables are imported by
+&scons; itself if set:
+</para>
+
 <variablelist>
   <varlistentry>
-  <term>SCONS_LIB_DIR</term>
-  <listitem>
-<para>Specifies the directory that contains the SCons Python module directory
-(e.g. /home/aroach/scons-src-0.01/src/engine).</para>
-
-  </listitem>
+    <term>SCONS_LIB_DIR</term>
+    <listitem>
+<para>Specifies the directory that contains the &scons;
+Python module directory (for example,
+<filename>/home/aroach/scons-src-0.01/src/engine</filename>).</para>
+    </listitem>
   </varlistentry>
+
   <varlistentry>
-  <term>SCONSFLAGS</term>
-  <listitem>
-<para>A string of options that will be used by scons in addition to those passed
-on the command line.</para>
+    <term>SCONSFLAGS</term>
+    <listitem>
+<para>A string of options that will be used by &scons;
+in addition to those passed on the command line.</para>
+    </listitem>
+  </varlistentry>
 
-  </listitem>
+  <varlistentry>
+    <term>SCONS_CACHE_MSVC_CONFIG</term>
+    <listitem>
+<para>If set, save the shell environment variables generated
+in setting up the Microsoft Visual C++ compiler (and/or Build Tools),
+to give these settings (expensive to generate) persistence
+between runs of &scons;.
+If set to a True-like value (<literal>1</literal>,
+<literal>true</literal> or
+<literal>True</literal>) will cache to a file named
+<filename>.scons_msvc_cache</filename> in the user's home directory.
+If set to a pathname, will use that pathname for the cache.</para>
+    </listitem>
   </varlistentry>
 </variablelist>
 </refsect1>
@@ -7220,8 +7243,9 @@ source code.</para>
 </refsect1>
 
 <refsect1 id='authors'><title>AUTHORS</title>
-<para>Originally: Steven Knight &lt;knight@baldmt.com&gt; and Anthony Roach &lt;aroach@electriceyeball.com&gt;
-Since 2010: The SCons Development Team &lt;scons-dev@scons.org&gt;
+<para>Originally: Steven Knight <email>knight@baldmt.com</email>
+and Anthony Roach <email>aroach@electriceyeball.com</email>.
+Since 2010: The SCons Development Team <email>scons-dev@scons.org</email>.
 </para>
 </refsect1>
 </refentry>
diff --git a/src/CHANGES.txt b/src/CHANGES.txt
index c45e86d..61f31b2 100755
--- a/src/CHANGES.txt
+++ b/src/CHANGES.txt
@@ -17,10 +17,11 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       the index from find() was not used.
     - Turn previously deprecated debug options into failures:
       --debug=tree, --debug=dtree, --debug=stree, --debug=nomemoizer.
-    - If SCONS_CACHE_MSVC_CONFIG env var is set, scons will cache the
-      results of past calls to vcvarsall.bat to a file; integrates with
-      existing memoizing of such vars. On vs2019 saves 5+ seconds per
-      scons invocation, which really helps test suite runs.
+    - If SCONS_CACHE_MSVC_CONFIG shell environment variable is set,
+      scons will cache the results of past calls to vcvarsall.bat to
+      a file; integrates with existing memoizing of such vars.
+      On vs2019 saves 5+ seconds per scons invocation, which really
+      helps test suite runs.
 
   From Jacek Kuczera:
     - Fix CheckFunc detection code for Visual 2019. Some functions
diff --git a/src/engine/SCons/Tool/MSCommon/common.py b/src/engine/SCons/Tool/MSCommon/common.py
index 0a7e0ef..d4997eb 100644
--- a/src/engine/SCons/Tool/MSCommon/common.py
+++ b/src/engine/SCons/Tool/MSCommon/common.py
@@ -35,47 +35,52 @@ import re
 
 import SCons.Util
 
+# internal-use so undocumented:
+# set to '-' to print to console, else set to filename to log to
 LOGFILE = os.environ.get('SCONS_MSCOMMON_DEBUG')
 if LOGFILE == '-':
     def debug(message):
         print(message)
 elif LOGFILE:
-    try:
-        import logging
-    except ImportError:
-        debug = lambda message: open(LOGFILE, 'a').write(message + '\n')
-    else:
-        logging.basicConfig(
-            format='%(relativeCreated)05dms:pid%(process)05d:MSCommon/%(filename)s:%(message)s',
-            filename=LOGFILE,
-            level=logging.DEBUG)
-        debug = logging.getLogger(name=__name__).debug
+    import logging
+    logging.basicConfig(
+        format='%(relativeCreated)05dms:pid%(process)05d:MSCommon/%(filename)s:%(message)s',
+        filename=LOGFILE,
+        level=logging.DEBUG)
+    debug = logging.getLogger(name=__name__).debug
 else:
     debug = lambda x: None
 
 
-CONFIG_CACHE = os.environ.get('SCONS_CACHE_MSVC_CONFIG', None)
-CONFIG_FILE = os.path.join(os.path.expanduser('~'), '.scons_msvc_cache')
-
+CONFIG_CACHE = os.environ.get('SCONS_CACHE_MSVC_CONFIG')
+if CONFIG_CACHE in ('1', 'true', 'True'):
+    CONFIG_CACHE = os.path.join(os.path.expanduser('~'), '.scons_msvc_cache')
 
 def read_script_env_cache():
-    """ fetch cached env vars if requested, else return empty dict """
+    """ fetch cached msvc env vars if requested, else return empty dict """
     envcache = {}
     if CONFIG_CACHE:
         try:
-            with open(CONFIG_FILE, 'r') as f:
+            with open(CONFIG_CACHE, 'r') as f:
                 envcache = json.load(f)
-        except FileNotFoundError:
+        #TODO can use more specific FileNotFoundError when py2 dropped
+        except IOError:
             pass
     return envcache
 
 
 def write_script_env_cache(cache):
-    """ write out cach of env vars if requested """
+    """ write out cache of msvc env vars if requested """
     if CONFIG_CACHE:
-        with open(CONFIG_FILE, 'w') as f:
-            #TODO: clean up if it fails
-            json.dump(cache, f, indent=2)
+        try:
+            with open(CONFIG_CACHE, 'w') as f:
+                json.dump(cache, f, indent=2)
+        except TypeError:
+            # data can't serialize to json, don't leave partial file
+            os.remove(CONFIG_CACHE)
+        except IOError:
+            # can't write the file, just skip
+            pass
 
 
 _is_win64 = None