Update MSCommon/README.rst formatting.

jcbrill · jcbrill · commit 41308408334e · 2024-03-25T07:48:51.000-04:00
diff --git a/SCons/Tool/MSCommon/README.rst b/SCons/Tool/MSCommon/README.rst
@@ -33,55 +33,37 @@ MSVC Detection Priority
 For msvc version specifications without an 'Exp' suffix, an express
 installation is used only when no other installation is detected.
 
-======= ======= ========================================================
-Product VCVer   Priority
-======= ======= ========================================================
-VS2022  14.3    Enterprise, Professional, Community, BuildTools
-------- ------- --------------------------------------------------------
-VS2019  14.2    Enterprise, Professional, Community, BuildTools
-------- ------- --------------------------------------------------------
-VS2017  14.1    Enterprise, Professional, Community, BuildTools, Express
-------- ------- --------------------------------------------------------
-VS2017  14.1Exp Express
-------- ------- --------------------------------------------------------
-VS2015  14.0    [Develop, BuildTools, CmdLine], Express
-------- ------- --------------------------------------------------------
-VS2015  14.0Exp Express
-------- ------- --------------------------------------------------------
-VS2013  12.0    Develop, Express
-------- ------- --------------------------------------------------------
-VS2013  12.0Exp Express
-------- ------- --------------------------------------------------------
-VS2012  11.0    Develop, Express
-------- ------- --------------------------------------------------------
-VS2012  11.0Exp Express
-------- ------- --------------------------------------------------------
-VS2010  10.0    Develop, Express
-------- ------- --------------------------------------------------------
-VS2010  10.0Exp Express
-------- ------- --------------------------------------------------------
-VS2008  9.0     Develop, VCForPython, Express
-------- ------- --------------------------------------------------------
-VS2008  9.0Exp  Express
-------- ------- --------------------------------------------------------
-VS2005  8.0     Develop, Express
-------- ------- --------------------------------------------------------
-VS2005  8.0Exp  Express
-------- ------- --------------------------------------------------------
-VS2003  7.1     Develop
-------- ------- --------------------------------------------------------
-VS2002  7.0     Develop
-------- ------- --------------------------------------------------------
-VS6.0   6.0     Develop
-======= ======= ========================================================
+=======  =======  ========================================================
+Product  VCVer    Priority
+=======  =======  ========================================================
+VS2022   14.3     Enterprise, Professional, Community, BuildTools
+VS2019   14.2     Enterprise, Professional, Community, BuildTools
+VS2017   14.1     Enterprise, Professional, Community, BuildTools, Express
+VS2017   14.1Exp  Express
+VS2015   14.0     [Develop, BuildTools, CmdLine], Express
+VS2015   14.0Exp  Express
+VS2013   12.0     Develop, Express
+VS2013   12.0Exp  Express
+VS2012   11.0     Develop, Express
+VS2012   11.0Exp  Express
+VS2010   10.0     Develop, Express
+VS2010   10.0Exp  Express
+VS2008   9.0      Develop, VCForPython, Express
+VS2008   9.0Exp   Express
+VS2005   8.0      Develop, Express
+VS2005   8.0Exp   Express
+VS2003   7.1      Develop
+VS2002   7.0      Develop
+VS6.0    6.0      Develop
+=======  =======  ========================================================
 
 Legend:
 
   Develop
-    devenv.com (or msdev.com) is detected.
+    devenv.com or msdev.com is detected.
   
   Express
-    WDExpress.exe (or VCExpress.exe) is detected.
+    WDExpress.exe or VCExpress.exe is detected.
   
   BuildTools [VS2015]
     The vcvarsall batch file dispatches to the buildtools batch file.
@@ -104,7 +86,9 @@ and/or linker build failures.
 
 The VS2015 BuildTools ``vcvarsall.bat`` batch file dispatches to the stand-alone buildtools
 batch file under certain circumstances. A fragment from the vcvarsall batch file is:
+
 ::
+
     if exist "%~dp0..\common7\IDE\devenv.exe" goto setup_VS
     if exist "%~dp0..\common7\IDE\wdexpress.exe" goto setup_VS
     if exist "%~dp0..\..\Microsoft Visual C++ Build Tools\vcbuildtools.bat" goto setup_buildsku
@@ -135,15 +119,19 @@ As installed, VS2015 Express does not support the ``store`` argument for the ``a
 architecture.  The generated ``store`` library paths include directories that do not exist.
 
 The store library paths appear in two places in the ``vcvarsx86_amd64`` batch file:
+
 ::
+
     :setstorelib
     @if exist "%VCINSTALLDIR%LIB\amd64\store" set LIB=%VCINSTALLDIR%LIB\amd64\store;%LIB%
     ...
     :setstorelibpath
     @if exist "%VCINSTALLDIR%LIB\amd64\store" set LIBPATH=%VCINSTALLDIR%LIB\amd64\store;%LIBPATH%
 
 The correct store library paths would be:
+
 ::
+
     :setstorelib
     @if exist "%VCINSTALLDIR%LIB\store\amd64" set LIB=%VCINSTALLDIR%LIB\store\amd64;%LIB%
     ...
@@ -157,15 +145,19 @@ As installed, VS2015 Express does not support the ``store`` argument for the ``a
 architecture.  The generated ``store`` library paths include directories that do not exist.
 
 The store library paths appear in two places in the ``vcvarsx86_arm`` batch file:
+
 ::
+
     :setstorelib
     @if exist "%VCINSTALLDIR%LIB\ARM\store" set LIB=%VCINSTALLDIR%LIB\ARM\store;%LIB%
     ...
     :setstorelibpath
     @if exist "%VCINSTALLDIR%LIB\ARM\store" set LIBPATH=%VCINSTALLDIR%LIB\ARM\store;%LIBPATH%
 
 The correct store library paths would be file:
+
 ::
+
     :setstorelib
     @if exist "%VCINSTALLDIR%LIB\store\ARM" set LIB=%VCINSTALLDIR%LIB\store\ARM;%LIB%
     ...
@@ -208,6 +200,7 @@ returns the msvc version and the msvc toolset version for the corresponding vers
 This is a proxy for using the toolset version for selection until that functionality can be added.
 
 Example usage:
+
 ::
 
     for version in [
@@ -240,6 +233,7 @@ Example usage:
             print('{}Query: {} version={}, prefer_newest={}'.format(newline, msg, version, prefer_newest))
 
 Example output fragment
+
 ::
 
     Build: _build003 {'MSVC_VERSION': '14.3', 'MSVC_TOOLSET_VERSION': '14.29.30133'}
@@ -267,6 +261,7 @@ added to the batch file argument list.  This is intended to make the cache more
 updates that may change the default toolset version and/or the default SDK version.
 
 Example usage:
+
 ::
 
     @echo Enabling scons cache ...
@@ -289,13 +284,15 @@ Enabling warnings to be produced for detected msvc batch file errors may provide
 for build failures. Refer to the documentation for details.
 
 Change the default policy:
+
 ::
 
     from SCons.Tool.MSCommon import msvc_set_scripterror_policy
 
     msvc_set_scripterror_policy('Warning')
 
 Specify the policy per-environment:
+
 ::
 
     env = Environment(MSVC_VERSION='14.3', MSVC_SPECTRE_LIBS=True, MSVC_SCRIPTERROR_POLICY='Warning')
@@ -321,6 +318,7 @@ On occasion, the raw vswhere output may prove useful especially if there are sus
 detection of installed msvc instances.
 
 Windows command-line sample invocations:
+
 ::
 
     @rem 64-Bit Windows
@@ -338,35 +336,29 @@ Batch File Arguments
 
 Supported MSVC batch file arguments by product:
 
-======= ======= ====== ======= =======
-Product UWP     SDK    Toolset Spectre
-======= ======= ====== ======= =======
-VS2022   X      X      X       X
-------- ------- ------ ------- -------
-VS2019   X      X      X       X
-------- ------- ------ ------- -------
-VS2017   X      X      X       X
-------- ------- ------ ------- -------
-VS2015   X [1]_ X [2]_
-======= ======= ====== ======= =======
+========  =======  =======  ========  =======
+Product   UWP      SDK      Toolset   Spectre
+========  =======  =======  ========  =======
+VS2022    X        X        X         X      
+VS2019    X        X        X         X      
+VS2017    X        X        X         X      
+VS2015    X [1]_   X [2]_                    
+========  =======  =======  ========  =======
 
 .. [1] The BuildTools edition does not support the ``store`` argument.  The Express edition
        supports the ``store`` argument for the ``x86`` target only.
 .. [2] The ``sdk version`` argument is not supported in the BuildTools and Express editions.
 
 Supported MSVC batch file arguments in SCons:
 
-======== ====================================== ===================================================
-Argument Construction Variable                  Script Argument Equivalent
-======== ====================================== ===================================================
-UWP      ``MSVC_UWP_APP=True``                  ``MSVC_SCRIPT_ARGS='store'``
--------- -------------------------------------- ---------------------------------------------------
-SDK      ``MSVC_SDK_VERSION='10.0.20348.0'``    ``MSVC_SCRIPT_ARGS='10.0.20348.0'``
--------- -------------------------------------- ---------------------------------------------------
-Toolset  ``MSVC_TOOLSET_VERSION='14.31.31103'`` ``MSVC_SCRIPT_ARGS='-vcvars_ver=14.31.31103'``
--------- -------------------------------------- ---------------------------------------------------
-Spectre  ``MSVC_SPECTRE_LIBS=True``             ``MSVC_SCRIPT_ARGS='-vcvars_spectre_libs=spectre'``
-======== ====================================== ===================================================
+========  ======================================  ===================================================
+Argument  Construction Variable                   Script Argument Equivalent
+========  ======================================  ===================================================
+UWP       ``MSVC_UWP_APP=True``                   ``MSVC_SCRIPT_ARGS='store'``
+SDK       ``MSVC_SDK_VERSION='10.0.20348.0'``     ``MSVC_SCRIPT_ARGS='10.0.20348.0'``
+Toolset   ``MSVC_TOOLSET_VERSION='14.31.31103'``  ``MSVC_SCRIPT_ARGS='-vcvars_ver=14.31.31103'``
+Spectre   ``MSVC_SPECTRE_LIBS=True``              ``MSVC_SCRIPT_ARGS='-vcvars_spectre_libs=spectre'``
+========  ======================================  ===================================================
 
 **MSVC_SCRIPT_ARGS contents are not validated.  Utilizing script arguments that have construction
 variable equivalents is discouraged and may lead to difficult to diagnose build errors.**
@@ -398,6 +390,7 @@ that the msvc batch files would return.  When using ``MSVC_SCRIPT_ARGS``, the
 toolset specification should be omitted entirely.
 
 Local installation and summary test results:
+
 ::
 
     VS2022\VC\Auxiliary\Build\Microsoft.VCToolsVersion.v143.default.txt
@@ -407,6 +400,7 @@ Local installation and summary test results:
         14.32.31326
 
 Toolset version summary:
+
 ::
 
     14.31.31103   Environment()
@@ -422,6 +416,7 @@ Toolset version summary:
     14.32.31326   Environment(MSVC_SCRIPT_ARGS=['-vcvars_ver=14.32'])
 
 VS2022\\Common7\\Tools\\vsdevcmd\\ext\\vcvars.bat usage fragment:
+
 ::
 
     @echo     -vcvars_ver=version : Version of VC++ Toolset to select
@@ -443,6 +438,7 @@ VS2022\\Common7\\Tools\\vsdevcmd\\ext\\vcvars.bat usage fragment:
     @echo                             SxS toolset to [VSInstallDir]\VC\MSVC\Tools\ directory.
 
 VS2022 batch file fragment to determine the default toolset version:
+
 ::
 
     @REM Add MSVC
@@ -469,13 +465,12 @@ Visual Studio Version Notes
 SDK Versions
 ------------
 
-==== =================
-SDK  Format
-==== =================
-10.0 10.0.XXXXX.Y [*]_
----- -----------------
-8.1  8.1
-==== =================
+====  =================
+SDK   Format
+====  =================
+10.0  10.0.XXXXX.Y [*]_
+8.1   8.1
+====  =================
 
 .. [*] The Windows 10 SDK version number is 10.0.20348.0 and earlier.
 
@@ -484,64 +479,42 @@ SDK  Format
 BuildTools Versions
 -------------------
 
-========== ===== ===== ========
-BuildTools VCVER CLVER MSVCRT
-========== ===== ===== ========
-v143       14.3   19.3 140/ucrt
----------- ----- ----- --------
-v142       14.2   19.2 140/ucrt
----------- ----- ----- --------
-v141       14.1   19.1 140/ucrt
----------- ----- ----- --------
-v140       14.0   19.0 140/ucrt
----------- ----- ----- --------
-v120       12.0   18.0 120
----------- ----- ----- --------
-v110       11.0   17.0 110
----------- ----- ----- --------
-v100       10.0   16.0 100
----------- ----- ----- --------
-v90         9.0   15.0  90
----------- ----- ----- --------
-v80         8.0   14.0  80
----------- ----- ----- --------
-v71         7.1   13.1  71
----------- ----- ----- --------
-v70         7.0   13.0  70
----------- ----- ----- --------
-v60         6.0   12.0  60
-========== ===== ===== ========
+==========  =====  =====  ========
+BuildTools  VCVER  CLVER  MSVCRT
+==========  =====  =====  ========
+v143        14.3   19.3   140/ucrt
+v142        14.2   19.2   140/ucrt
+v141        14.1   19.1   140/ucrt
+v140        14.0   19.0   140/ucrt
+v120        12.0   18.0   120
+v110        11.0   17.0   110
+v100        10.0   16.0   100
+v90         9.0    15.0   90
+v80         8.0    14.0   80
+v71         7.1    13.1   71
+v70         7.0    13.0   70
+v60         6.0    12.0   60
+==========  =====  =====  ========
 
 Product Versions
 ----------------
 
-======== ===== ========= ======================
-Product  VSVER SDK       BuildTools
-======== ===== ========= ======================
-2022     17.0  10.0, 8.1 v143, v142, v141, v140
--------- ----- --------- ----------------------
-2019     16.0  10.0, 8.1 v142, v141, v140
--------- ----- --------- ----------------------
-2017     15.0  10.0, 8.1 v141, v140
--------- ----- --------- ----------------------
-2015     14.0  10.0, 8.1 v140
--------- ----- --------- ----------------------
-2013     12.0            v120
--------- ----- --------- ----------------------
-2012     11.0            v110
--------- ----- --------- ----------------------
-2010     10.0            v100
--------- ----- --------- ----------------------
-2008      9.0            v90
--------- ----- --------- ----------------------
-2005      8.0            v80
--------- ----- --------- ----------------------
-2003.NET  7.1            v71
--------- ----- --------- ----------------------
-2002.NET  7.0            v70
--------- ----- --------- ----------------------
-6.0       6.0            v60
-======== ===== ========= ======================
+=========  ======  ==========  ======================
+Product    VSVER   SDK         BuildTools
+=========  ======  ==========  ======================
+2022       17.0    10.0, 8.1   v143, v142, v141, v140
+2019       16.0    10.0, 8.1   v142, v141, v140
+2017       15.0    10.0, 8.1   v141, v140
+2015       14.0    10.0, 8.1   v140
+2013       12.0                v120
+2012       11.0                v110
+2010       10.0                v100
+2008       9.0                 v90
+2005       8.0                 v80
+2003.NET   7.1                 v71
+2002.NET   7.0                 v70
+6.0        6.0                 v60
+=========  ======  ==========  ======================
 
 
 SCons Implementation Notes
