[PR 3462] update doc/comments for msvc-env-cache

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

3 files changed, 35 insertions, 22 deletions

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index e210e76..1b8ee43 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -7218,26 +7218,32 @@ in addition to those passed on the command line.</para>
   <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, which are expensive to generate, persistence
+<para>(Windows only). If set, save the shell environment variables
+generated when setting up the Microsoft Visual C++ compiler
+(and/or Build Tools) to a file to give these settings, 
+which are expensive to generate, persistence
 across &scons; invocations.
-If set to a True-like value (<literal>"1"</literal>,
+Use of this option is primarily intended to aid performance
+in tightly controlled Continuous Integration setups.</para>
+
+<para>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>
-<para>
-Note: this behavior is not enabled by default because it
-might be somewhat fragile: while each major tool version
-(e.g. Visual Studio 2018 vs 2019) will get separate
-entries, if toolset updates cause a change
+
+<para>Note: use this cache with caution as it
+might be somewhat fragile: while each major toolset version
+(e.g. Visual Studio 2017 vs 2019) and architecture pair will get separate
+cache entries, if toolset updates cause a change
 to settings within a given release series, &scons; will not
-detect this and will fetch old settings.
-In case of problems, just remove the cache file.
-Use of this option is primarily intended to aid performance
-for tightly controlled Continuous Integration setups.
-</para>
+detect the change and will reuse old settings.
+Remove the cache file in case of problems with this.
+&scons; will ignore failures reading or writing the file
+and will silently revert to non-cached behavior in such cases.</para>
+
+<para>Since &scons; 3.1.</para>
+
     </listitem>
   </varlistentry>
 </variablelist>
diff --git a/src/engine/SCons/Tool/MSCommon/common.py b/src/engine/SCons/Tool/MSCommon/common.py
index ad371e9..bbccf61 100644
--- a/src/engine/SCons/Tool/MSCommon/common.py
+++ b/src/engine/SCons/Tool/MSCommon/common.py
@@ -36,7 +36,7 @@ import sys
 
 import SCons.Util
 
-# internal-use so undocumented:
+# SCONS_MSCOMMON_DEBUG is 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 == '-':
@@ -53,6 +53,7 @@ else:
     debug = lambda x: None
 
 
+# SCONS_CACHE_MSVC_CONFIG is public, and is documented.
 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')
@@ -66,6 +67,7 @@ def read_script_env_cache():
                 envcache = json.load(f)
         #TODO can use more specific FileNotFoundError when py2 dropped
         except IOError:
+            # don't fail if no cache file, just proceed without it
             pass
     return envcache
 
diff --git a/src/engine/SCons/Tool/MSCommon/vc.py b/src/engine/SCons/Tool/MSCommon/vc.py
index d321f43..4f6048d 100644
--- a/src/engine/SCons/Tool/MSCommon/vc.py
+++ b/src/engine/SCons/Tool/MSCommon/vc.py
@@ -591,12 +591,15 @@ def reset_installed_vcs():
 # we can greatly improve the speed of the second and subsequent Environment
 # (or Clone) calls by memoizing the environment variables set by vcvars*.bat.
 #
-# Updated: by 2018, vcvarsall.bat had gotten so expensive it was breaking
-# CI builds because the test suite starts scons so many times and the existing
-# memo logic only helped with repeated calls within the same scons run;
-# with VS2019 it got even slower and an optional cache file was introduced.
-# The cache now also stores only the parsed vars, not the entire output
-# of running the batch file - saves a bit of time not parsing every time.
+# Updated: by 2018, vcvarsall.bat had gotten so expensive (vs2017 era)
+# it was breaking CI builds because the test suite starts scons so many
+# times and the existing memo logic only helped with repeated calls
+# within the same scons run. Windows builds on the CI system were split
+# into chunks to get around single-build time limits.
+# With VS2019 it got even slower and an optional persistent cache file
+# was introduced. The cache now also stores only the parsed vars, 
+# not the entire output of running the batch file - saves a bit
+# of time not parsing every time.
 
 script_env_cache = None
 
@@ -621,7 +624,8 @@ def script_env(script, args=None):
         # once we updated cache, give a chance to write out if user wanted
         common.write_script_env_cache(script_env_cache)
     else:
-        # if we "hit" data from the json file, we have a Py2 problem:
+        #TODO: Python 2 cleanup
+        # If we "hit" data from the json file, we have a Py2 problem:
         # keys & values will be unicode. don't detect, just convert.
         if sys.version_info[0] == 2:
             def convert(data):
@@ -635,6 +639,7 @@ def script_env(script, args=None):
                     return data
 
             cache_data = convert(cache_data)
+ 
     return cache_data
 
 def get_default_version(env):