From eaaeab30cc6a559cf458c6ee60ebc25aa919c6fc Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 18 Jan 2023 08:19:27 -0700 Subject: Doc: update msvc, add version table [skip appveyor] The changes in 4.4 didn't marke new construction variables with the now preferred version add marker, so added these. The references to different versions gets so confusing that to try to help added a version correspondence table to the MSVC_VERSION construction varaiable doc. Signed-off-by: Mats Wichmann --- RELEASE.txt | 2 + SCons/Tool/msvc.xml | 305 ++++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 241 insertions(+), 66 deletions(-) diff --git a/RELEASE.txt b/RELEASE.txt index 35fd845..7b08898 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -117,6 +117,8 @@ DOCUMENTATION - Updated the User Guide chapter on variant directories with more explanation, and the introduction of terms like "out of tree" that may help in forming a mental model. +- Updated MSVC documentation - adds "version added" annotations on recently + added construction variables and provides a version-mapping table. DEVELOPMENT ----------- diff --git a/SCons/Tool/msvc.xml b/SCons/Tool/msvc.xml index c26c20d..bf2e267 100644 --- a/SCons/Tool/msvc.xml +++ b/SCons/Tool/msvc.xml @@ -1,31 +1,10 @@ -Sets construction variables for the Microsoft Visual C/C++ compiler. +Sets &consvars; for the Microsoft Visual C/C++ compiler. @@ -96,7 +75,17 @@ Sets construction variables for the Microsoft Visual C/C++ compiler. PCH PCHSTOP PDB +MSVC_VERSION +MSVC_USE_SCRIPT +MSVC_USE_SCRIPT_ARGS +MSVC_USE_SETTINGS MSVC_NOTFOUND_POLICY +MSVC_SCRIPTERROR_POLICY +MSVC_SCRIPT_ARGS +MSVC_SDK_VERSION +MSVC_TOOLSET_VERSION +MSVC_SPECTRE_LIBS + @@ -110,7 +99,7 @@ file as the second element. Normally the object file is ignored. This builder is only provided when Microsoft Visual C++ is being used as the compiler. The &b-PCH; builder is generally used in -conjunction with the &cv-link-PCH; construction variable to force object files to use +conjunction with the &cv-link-PCH; &consvar; to force object files to use the precompiled header: @@ -148,7 +137,7 @@ Options added to the compiler command line to support building with precompiled headers. The default value expands expands to the appropriate Microsoft Visual C++ command-line options -when the &cv-link-PCH; construction variable is set. +when the &cv-link-PCH; &consvar; is set. @@ -161,7 +150,7 @@ to support storing debugging information in a Microsoft Visual C++ PDB file. The default value expands expands to appropriate Microsoft Visual C++ command-line options -when the &cv-link-PDB; construction variable is set. +when the &cv-link-PDB; &consvar; is set. @@ -208,11 +197,11 @@ compilation of object files when calling the Microsoft Visual C/C++ compiler. All compilations of source files from the same source directory that generate target files in a same output directory -and were configured in SCons using the same construction environment +and were configured in SCons using the same &consenv; will be built in a single call to the compiler. Only source files that have changed since their object files were built will be passed to each compiler invocation -(via the &cv-link-CHANGED_SOURCES; construction variable). +(via the &cv-link-CHANGED_SOURCES; &consvar;). Any compilations where the object (target) file base name (minus the .obj) does not match the source file base name @@ -261,9 +250,9 @@ If this is not set, then &cv-link-PCHCOM; (the command line) is displayed. -A construction variable that, when expanded, +A &consvar; that, when expanded, adds the flag to the command line -only if the &cv-link-PDB; construction variable is set. +only if the &cv-link-PDB; &consvar; is set. @@ -324,7 +313,7 @@ The flags passed to the resource compiler by the &b-link-RES; builder. -An automatically-generated construction variable +An automatically-generated &consvar; containing the command-line options for specifying directories to be searched by the resource compiler. @@ -343,7 +332,7 @@ of each directory in &cv-link-CPPPATH;. The prefix (flag) used to specify an include directory on the resource compiler command line. This will be prepended to the beginning of each directory -in the &cv-link-CPPPATH; construction variable +in the &cv-link-CPPPATH; &consvar; when the &cv-link-RCINCFLAGS; variable is expanded. @@ -355,7 +344,7 @@ when the &cv-link-RCINCFLAGS; variable is expanded. The suffix used to specify an include directory on the resource compiler command line. This will be appended to the end of each directory -in the &cv-link-CPPPATH; construction variable +in the &cv-link-CPPPATH; &consvar; when the &cv-link-RCINCFLAGS; variable is expanded. @@ -365,12 +354,10 @@ when the &cv-link-RCINCFLAGS; variable is expanded. Sets the preferred version of Microsoft Visual C/C++ to use. - - - +If the specified version is unavailable (not installed, +or not discoverable), tool initialization will fail. If &cv-MSVC_VERSION; is not set, SCons will (by default) select the -latest version of Visual C/C++ installed on your system. If the -specified version isn't installed, tool initialization will fail. +latest version of Visual C/C++ installed on your system. @@ -383,28 +370,186 @@ loaded into the environment. -Valid values for Windows are -14.3, -14.2, -14.1, -14.1Exp, -14.0, -14.0Exp, -12.0, -12.0Exp, -11.0, -11.0Exp, -10.0, -10.0Exp, -9.0, -9.0Exp, -8.0, -8.0Exp, -7.1, -7.0, -and 6.0. -Versions ending in Exp refer to "Express" or -"Express for Desktop" editions. +The valid values for &cv-MSVC_VERSION; represent major versions +of the compiler, except that versions ending in Exp +refer to "Express" or "Express for Desktop" Visual Studio editions, +which require distict entries because they use a different +filesystem layout and have some feature limitations compared to +the full version. +The following table shows correspondence +of the selector string to various version indicators +('x' is used as a placeholder for +a single digit that can vary). +Note that it is not necessary to install Visual Studio +to build with &SCons; (for example, you can install only +Build Tools), but if Visual Studio is installed, +additional builders such as &b-link-MSVSSolution; and +&b-link-MSVSProject; become avaialable and will +correspond to the indicated versions. + + + + + + + + + + + + SCons Key + MSVC++ Version + _MSVC_VER + VS Product + MSBuild/VS Version + + + + + 14.3 + 14.3x + 193x + Visual Studio 2022 + 17.x + + + 14.2 + 14.2x + 192x + Visual Studio 2019 + 16.x, 16.1x + + + 14.1 + 14.1 or 14.1x + 191x + Visual Studio 2017 + 15.x + + + 14.1Exp + 14.1 + 1910 + Visual Studio 2017 Express + 15.0 + + + 14.0 + 14.0 + 1900 + Visual Studio 2015 + 14.0 + + + 14.0Exp + 14.0 + 1900 + Visual Studio 2015 Express + 14.0 + + + 12.0 + 12.0 + 1800 + Visual Studio 2013 + 12.0 + + + 12.0Exp + 12.0 + 1800 + Visual Studio 2013 Express + 12.0 + + + 11.0 + 11.0 + 1700 + Visual Studio 2012 + 11.0 + + + 11.0Exp + 11.0 + 1700 + Visual Studio 2012 Express + 11.0 + + + 10.0 + 10.0 + 1600 + Visual Studio 2010 + 10.0 + + + 10.0Exp + 10.0 + 1600 + Visual C++ Express 2010 + 10.0 + + + 9.0 + 9.0 + 1500 + Visual Studio 2008 + 9.0 + + + 9.0Exp + 9.0 + 1500 + Visual C++ Express 2008 + 9.0 + + + 8.0 + 8.0 + 1400 + Visual Studio 2005 + 8.0 + + + 8.0Exp + 8.0 + 1400 + Visual C++ Express 2005 + 8.0 + + + 7.1 + 7.1 + 1300 + Visual Studio .NET 2003 + 7.1 + + + 7.0 + 7.0 + 1200 + Visual Studio .NET 2002 + 7.0 + + + 6.0 + 6.0 + 1100 + Visual Studio 6.0 + 6.0 + + + + + + +The compilation environment can be further or more precisely specified through the +use of several other &consvars;: see the descriptions of +&cv-link-MSVC_TOOLSET_VERSION;, +&cv-link-MSVC_SDK_VERSION;, +&cv-link-MSVC_USE_SCRIPT;, +&cv-link-MSVC_USE_SCRIPT_ARGS;, +and &cv-link-MSVC_USE_SETTINGS;. @@ -433,7 +578,7 @@ This can be useful to force the use of a compiler version that Setting &cv-MSVC_USE_SCRIPT; to None bypasses the Visual Studio autodetection entirely; -use this if you are running SCons in a Visual Studio cmd +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. @@ -441,6 +586,12 @@ you don't want &SCons; to change anything. &cv-MSVC_USE_SCRIPT; ignores &cv-link-MSVC_VERSION; and &cv-link-TARGET_ARCH;. + +Changed in version 4.4: +new &cv-link-MSVC_USE_SCRIPT_ARGS; provides a +way to pass arguments. + + @@ -449,6 +600,9 @@ you don't want &SCons; to change anything. Provides arguments passed to the script &cv-link-MSVC_USE_SCRIPT;. + +New in version 4.4 + @@ -529,11 +683,15 @@ therefore may change at any time. The burden is on the user to ensure the dictionary contents are minimally sufficient to ensure successful builds. - + + + +New in version 4.4 + @@ -780,6 +938,8 @@ When &cv-MSVC_NOTFOUND_POLICY; is not specified, the default &scons; behavior is subject to the conditions listed above. The default &scons; behavior may change in the future. +New in version 4.4 + @@ -831,6 +991,9 @@ Issue a warning when msvc batch file errors are detected. Suppress msvc batch file error messages. + +New in version 4.4 + @@ -905,6 +1068,8 @@ when setting the script error policy to raise an exception (e.g., 'Erro +New in version 4.4 + @@ -916,8 +1081,8 @@ Pass user-defined arguments to the Visual C++ batch file determined via autodete &cv-MSVC_SCRIPT_ARGS; is available for msvc batch file arguments that do not have first-class support -via construction variables or when there is an issue with the appropriate construction variable validation. -When available, it is recommended to use the appropriate construction variables (e.g., &cv-link-MSVC_TOOLSET_VERSION;) +via &consvars; or when there is an issue with the appropriate &consvar; validation. +When available, it is recommended to use the appropriate &consvars; (e.g., &cv-link-MSVC_TOOLSET_VERSION;) rather than &cv-MSVC_SCRIPT_ARGS; arguments. @@ -1041,6 +1206,8 @@ and compatible with the version of msvc selected. +New in version 4.4 + @@ -1159,6 +1326,8 @@ specify a Windows 10 SDK (e.g., '10.0.20348.0') for the build +New in version 4.4 + @@ -1329,6 +1498,8 @@ The burden is on the user to ensure the requisite toolset target architecture bu +New in version 4.4 + @@ -1409,6 +1580,8 @@ The burden is on the user to ensure the requisite libraries with spectre mitigat +New in version 4.4 + -- cgit v0.12 From f293dd97feafeb9faf9ac805323d173bc8173176 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Mon, 23 Jan 2023 11:11:36 -0800 Subject: [ci skip] Add blurb to CHANGES.txt --- CHANGES.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGES.txt b/CHANGES.txt index 279ef2e..90b0aee 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -106,6 +106,9 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER not be cached because the emitted filename contained a '$' and when looked up through a node ended up generating a Python SyntaxError because it was passed through scons_subst(). + - Updated MSVC documentation - adds "version added" annotations on recently + added construction variables and provides a version-mapping table. + RELEASE 4.4.0 - Sat, 30 Jul 2022 14:08:29 -0700 -- cgit v0.12