Update vswhere function api and update MSCommon/README.rst

Changes:
* add vswhere_exe argument to msvc_quert_version_toolset function in MSCommon/README.rst
* fix: pass normalized path for vswhere_norm in vswhere binary named tuple constructor
* add freeze argument for vswhere_register_executable

Author: jcbrill

SCons/Tool/MSCommon/README.rst

@@ -207,13 +207,15 @@ The following issues are known to exist:
 Experimental Features
 =====================
 
-msvc_query_version_toolset(version=None, prefer_newest=True)
-------------------------------------------------------------
+msvc_query_version_toolset(version=None, prefer_newest=True, vswhere_exe=None)
+------------------------------------------------------------------------------
 
 The experimental function ``msvc_query_version_toolset`` was added to ``MSCommon/vc.py``
-and is available via the ``SCons.Tool.MSCommon`` namespace. This function takes a version
-specification or a toolset version specification and a product preference as arguments and
-returns the msvc version and the msvc toolset version for the corresponding version specification.
+and is available via the ``SCons.Tool.MSCommon`` namespace.
+
+This function takes a version specification or a toolset version specification, an optional product
+preference, and an optional vswhere executable location as arguments and returns the msvc version and
+the msvc toolset version for the corresponding version specification.
 
 This is a proxy for using the toolset version for selection until that functionality can be added.
 

SCons/Tool/MSCommon/vc.py

@@ -978,7 +978,7 @@ def factory(cls, vswhere_exe):
 
         vswhere_binary = cls(
             vswhere_exe=vswhere_exe,
-            vswhere_norm=vswhere_exe,
+            vswhere_norm=vswhere_norm,
         )
 
         cls._cache_vswhere_paths[vswhere_exe] = vswhere_binary
@@ -1103,6 +1103,11 @@ def _vswhere_all_executables(cls):
                 vswhere_exe_list.append(vswhere_binary.vswhere_exe)
         return vswhere_exe_list
 
+    @classmethod
+    def is_frozen(cls) -> bool:
+        rval = bool(cls.vswhere_frozen_flag)
+        return rval
+
     @classmethod
     def freeze_vswhere_binary(cls):
         if not cls.vswhere_frozen_flag:
@@ -1141,7 +1146,7 @@ def _vswhere_priority_group(cls, priority):
         return group
 
     @classmethod
-    def register_vswhere_executable(cls, vswhere_exe, priority=None) -> bool:
+    def register_vswhere_executable(cls, vswhere_exe, priority=None):
 
         vswhere_binary = cls.UNDEFINED_VSWHERE_BINARY
 
@@ -1222,11 +1227,27 @@ def vswhere_freeze_env(cls, env):
         return frozen_binary, vswhere_binary
 
 # external use
-vswhere_register_executable = _VSWhereExecutable.register_vswhere_executable
-vswhere_get_executable = _VSWhereExecutable.get_vswhere_executable
-vswhere_freeze_executable = _VSWhereExecutable.freeze_vswhere_executable
 
-# internal use
+def vswhere_register_executable(vswhere_exe, priority=None, freeze=False):
+    debug('register vswhere_exe=%s, priority=%s, freeze=%s', repr(vswhere_exe), repr(priority), repr(freeze))
+    _VSWhereExecutable.register_vswhere_executable(vswhere_exe, priority=priority)
+    if freeze:
+        _VSWhereExecutable.freeze_vswhere_executable()
+    rval = _VSWhereExecutable.get_vswhere_executable()
+    debug('current vswhere_exe=%s, is_frozen=%s', repr(rval), _VSWhereExecutable.is_frozen())
+    return vswhere_exe
+
+def vswhere_get_executable():
+    debug('')
+    vswhere_exe = _VSWhereExecutable.get_vswhere_executable()
+    return vswhere_exe
+
+def vswhere_freeze_executable():
+    debug('')
+    vswhere_exe = _VSWhereExecutable.freeze_vswhere_executable()
+    return vswhere_exe
+
+# internal use only
 vswhere_freeze_env = _VSWhereExecutable.vswhere_freeze_env
 
 def msvc_find_vswhere():