%scons; %builders-mod; %functions-mod; %tools-mod; %variables-mod; ]>

Sets construction variables for the Microsoft Visual C/C++ compiler.

CCDEPFLAGS CCPDBFLAGS CCPCHFLAGS CC CCFLAGS CFLAGS CCCOM SHCC SHCCFLAGS SHCFLAGS SHCCCOM CXX CXXFLAGS CXXCOM SHCXX SHCXXFLAGS SHCXXCOM CPPDEFPREFIX CPPDEFSUFFIX INCPREFIX INCSUFFIX RC RCFLAGS RCCOM BUILDERS OBJPREFIX OBJSUFFIX SHOBJPREFIX SHOBJSUFFIX CFILESUFFIX CXXFILESUFFIX PCHPDBFLAGS PCHCOM CCCOMSTR SHCCCOMSTR CXXCOMSTR SHCXXCOMSTR PCH PCHSTOP PDB MSVC_NOTFOUND_POLICY

Builds a Microsoft Visual C++ precompiled header. Calling this builder returns a list of two targets: the PCH as the first element, and the object 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 the precompiled header: env['PCH'] = env.PCH('StdAfx.cpp')[0]

Builds a Microsoft Visual C++ resource file. This builder method is only provided when Microsoft Visual C++ or MinGW is being used as the compiler. The .res (or .o for MinGW) suffix is added to the target name if no other suffix is given. The source file is scanned for implicit dependencies as though it were a C file. Example: env.RES('resource.rc')

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.

Options added to the compiler command line 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. The Visual C++ compiler option that SCons uses by default to generate PDB information is . This works correctly with parallel () builds because it embeds the debug information in the intermediate object files, as opposed to sharing a single PDB file between multiple object files. This is also the only way to get debug information embedded into a static library. Using the instead may yield improved link-time performance, although parallel builds will no longer work. You can generate PDB files with the switch by overriding the default &cv-link-CCPDBFLAGS; variable as follows: env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}'] An alternative would be to use the to put the debugging information in a separate .pdb file for each object file by overriding the &cv-link-CCPDBFLAGS; variable as follows: env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'

When set to any true value, specifies that SCons should batch 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 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). Any compilations where the object (target) file base name (minus the .obj) does not match the source file base name will be compiled separately.

The Microsoft Visual C++ precompiled header that will be used when compiling object files. This variable is ignored by tools other than Microsoft Visual C++. When this variable is defined SCons will add options to the compiler command line to cause it to use the precompiled header, and will also set up the dependencies for the PCH file. Example: env['PCH'] = File('StdAfx.pch')

The command line used by the &b-link-PCH; builder to generated a precompiled header.

The string displayed when generating a precompiled header. If this is not set, then &cv-link-PCHCOM; (the command line) is displayed.

A construction variable that, when expanded, adds the flag to the command line only if the &cv-link-PDB; construction variable is set.

This variable specifies how much of a source file is precompiled. This variable is ignored by tools other than Microsoft Visual C++, or when the PCH variable is not being used. When this variable is define it must be a string that is the name of the header that is included at the end of the precompiled portion of the source files, or the empty string if the "#pragma hrdstop" construct is being used: env['PCHSTOP'] = 'StdAfx.h'

The resource compiler used to build a Microsoft Visual C++ resource file.

The command line used to build a Microsoft Visual C++ resource file.

The string displayed when invoking the resource compiler to build a Microsoft Visual C++ resource file. If this is not set, then &cv-link-RCCOM; (the command line) is displayed.

The flags passed to the resource compiler by the &b-link-RES; builder.

An automatically-generated construction variable containing the command-line options for specifying directories to be searched by the resource compiler. The value of &cv-RCINCFLAGS; is created by respectively prepending and appending &cv-link-RCINCPREFIX; and &cv-link-RCINCSUFFIX; to the beginning and end 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 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 when the &cv-link-RCINCFLAGS; variable is expanded.

Sets the preferred version of Microsoft Visual C/C++ to use. 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. &cv-MSVC_VERSION; must be passed as an argument to the &f-link-Environment; constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is loaded via the default tools list or via a tools list passed to the &f-link-Environment; constructor. Otherwise, &cv-MSVC_VERSION; must be set before the first msvc tool is 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.

Use a batch script to set up the Microsoft Visual C++ compiler. If set to the name of a Visual Studio .bat file (e.g. vcvars.bat), &SCons; will run that batch file instead of the auto-detected one, and extract the relevant variables from the result (typically %INCLUDE%, %LIB%, and %PATH%) for supplying to the build. This can be useful to force the use of a compiler version that &SCons; does not detect. &cv-link-MSVC_USE_SCRIPT_ARGS; provides arguments passed to this script. 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 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. &cv-MSVC_USE_SCRIPT; ignores &cv-link-MSVC_VERSION; and &cv-link-TARGET_ARCH;.

Provides arguments passed to the script &cv-link-MSVC_USE_SCRIPT;.

Use a dictionary to set up the Microsoft Visual C++ compiler. &cv-MSVC_USE_SETTINGS; is ignored when &cv-link-MSVC_USE_SCRIPT; is defined and/or when &cv-MSVC_USE_SETTINGS; is set to None. The dictionary is used to populate the environment with the relevant variables (typically %INCLUDE%, %LIB%, and %PATH%) for supplying to the build. This can be useful to force the use of a compiler environment that &SCons; does not configure correctly. This is an alternative to manually configuring the environment when bypassing Visual Studio autodetection entirely by setting &cv-link-MSVC_USE_SCRIPT; to None. Here is an example of configuring a build environment using the Microsoft Visual C/C++ compiler included in the Microsoft SDK on a 64-bit host and building for a 64-bit architecture: # Microsoft SDK 6.0 (MSVC 8.0): 64-bit host and 64-bit target msvc_use_settings = { "PATH": [ "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Bin\\x64", "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin\\x64", "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin", "C:\\Windows\\Microsoft.NET\\Framework\\v2.0.50727", "C:\\Windows\\system32", "C:\\Windows", "C:\\Windows\\System32\\Wbem", "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\" ], "INCLUDE": [ "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Include", "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Include\\Sys", "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Include", "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Include\\gl", ], "LIB": [ "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Lib\\x64", "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Lib\\x64", ], "LIBPATH": [], "VSCMD_ARG_app_plat": [], "VCINSTALLDIR": [], "VCToolsInstallDir": [] } # Specifying MSVC_VERSION is recommended env = Environment(MSVC_VERSION='8.0', MSVC_USE_SETTINGS=msvc_use_settings) Important usage details: &cv-MSVC_USE_SETTINGS; must be passed as an argument to the &f-link-Environment; constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is loaded via the default tools list or via a tools list passed to the &f-link-Environment; constructor. Otherwise, &cv-MSVC_USE_SETTINGS; must be set before the first msvc tool is loaded into the environment. The dictionary content requirements are based on the internal msvc implementation and therefore may change at any time. The burden is on the user to ensure the dictionary contents are minimally sufficient to ensure successful builds.

Build with the Universal Windows Platform (UWP) application Visual C++ libraries. The valid values for &cv-MSVC_UWP_APP; are: True, '1', False, '0', or None. When &cv-MSVC_UWP_APP; is enabled (i.e., True or '1'), the Visual C++ environment will be set up to point to the Windows Store compatible libraries and Visual C++ runtimes. In doing so, any libraries that are built will be able to be used in a UWP App and published to the Windows Store. An exception is raised when any of the following conditions are satisfied: &cv-MSVC_UWP_APP; is enabled for Visual Studio 2013 and earlier. &cv-MSVC_UWP_APP; is enabled and a UWP argument is specified in &cv-link-MSVC_SCRIPT_ARGS;. Multiple UWP declarations via &cv-MSVC_UWP_APP; and &cv-link-MSVC_SCRIPT_ARGS; are not allowed. Example - A Visual Studio 2022 build for the Universal Windows Platform: env = Environment(MSVC_VERSION='14.3', MSVC_UWP_APP=True) Important usage details: &cv-MSVC_UWP_APP; must be passed as an argument to the &f-link-Environment; constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is loaded via the default tools list or via a tools list passed to the &f-link-Environment; constructor. Otherwise, &cv-MSVC_UWP_APP; must be set before the first msvc tool is loaded into the environment. The existence of the UWP libraries is not verified when &cv-MSVC_UWP_APP; is enabled which could result in build failures. The burden is on the user to ensure the requisite UWP libraries are installed.

Specify the location of vswhere.exe. The vswhere.exe executable is distributed with Microsoft Visual Studio and Build Tools since the 2017 edition, but is also available standalone. It provides full information about installations of 2017 and later editions. With the argument, vswhere.exe can detect installations of the 2010 through 2015 editions with limited data returned. If VSWHERE is set, SCons will use that location. Otherwise SCons will look in the following locations and set VSWHERE to the path of the first vswhere.exe located. %ProgramFiles(x86)%\Microsoft Visual Studio\Installer %ProgramFiles%\Microsoft Visual Studio\Installer %ChocolateyInstall%\bin Note that VSWHERE must be set at the same time or prior to any of &t-link-msvc;, &t-link-msvs; , and/or &t-link-mslink; &f-link-Tool; being initialized. Either set it as follows env = Environment(VSWHERE='c:/my/path/to/vswhere') or if your &consenv; is created specifying an empty tools list (or a list of tools which omits all of default, msvs, msvc, and mslink), and also before &f-link-env-Tool; is called to ininitialize any of those tools: env = Environment(tools=[]) env['VSWHERE'] = r'c:/my/vswhere/install/location/vswhere.exe' env.Tool('msvc') env.Tool('mslink') env.Tool('msvs')

Specify the &scons; behavior when the Microsoft Visual C/C++ compiler is not detected. The &cv-MSVC_NOTFOUND_POLICY; specifies the &scons; behavior when no msvc versions are detected or when the requested msvc version is not detected. The valid values for &cv-MSVC_NOTFOUND_POLICY; and the corresponding &scons; behavior are: 'Error' or 'Exception' Raise an exception when no msvc versions are detected or when the requested msvc version is not detected. 'Warning' or 'Warn' Issue a warning and continue when no msvc versions are detected or when the requested msvc version is not detected. Depending on usage, this could result in build failure(s). 'Ignore' or 'Suppress' Take no action and continue when no msvc versions are detected or when the requested msvc version is not detected. Depending on usage, this could result in build failure(s). Note: in addition to the camel case values shown above, lower case and upper case values are accepted as well. The &cv-MSVC_NOTFOUND_POLICY; is applied when any of the following conditions are satisfied: &cv-MSVC_VERSION; is specified, the default tools list is implicitly defined (i.e., the tools list is not specified), and the default tools list contains one or more of the msvc tools. &cv-MSVC_VERSION; is specified, the default tools list is explicitly specified (e.g., tools=['default']), and the default tools list contains one or more of the msvc tools. A non-default tools list is specified that contains one or more of the msvc tools (e.g., tools=['msvc', 'mslink']). The &cv-MSVC_NOTFOUND_POLICY; is ignored when any of the following conditions are satisfied: &cv-MSVC_VERSION; is not specified and the default tools list is implicitly defined (i.e., the tools list is not specified). &cv-MSVC_VERSION; is not specified and the default tools list is explicitly specified (e.g., tools=['default']). A non-default tool list is specified that does not contain any of the msvc tools (e.g., tools=['mingw']). Important usage details: &cv-MSVC_NOTFOUND_POLICY; must be passed as an argument to the &f-link-Environment; constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is loaded via the default tools list or via a tools list passed to the &f-link-Environment; constructor. Otherwise, &cv-MSVC_NOTFOUND_POLICY; must be set before the first msvc tool is loaded into the environment. When &cv-MSVC_NOTFOUND_POLICY; is not specified, the default &scons; behavior is to issue a warning and continue subject to the conditions listed above. The default &scons; behavior may change in the future.

Specify the &scons; behavior when Microsoft Visual C/C++ batch file errors are detected. The &cv-MSVC_SCRIPTERROR_POLICY; specifies the &scons; behavior when msvc batch file errors are detected. When &cv-MSVC_SCRIPTERROR_POLICY; is not specified, the default &scons; behavior is to suppress msvc batch file error messages. The root cause of msvc build failures may be difficult to diagnose. In these situations, setting the &scons; behavior to issue a warning when msvc batch file errors are detected may produce additional diagnostic information. The valid values for &cv-MSVC_SCRIPTERROR_POLICY; and the corresponding &scons; behavior are: 'Error' or 'Exception' Raise an exception when msvc batch file errors are detected. 'Warning' or 'Warn' Issue a warning when msvc batch file errors are detected. 'Ignore' or 'Suppress' Suppress msvc batch file error messages. Note: in addition to the camel case values shown above, lower case and upper case values are accepted as well. Example 1 - A Visual Studio 2022 build with user-defined script arguments: env = environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['8.1', 'store', '-vcvars_ver=14.1']) env.Program('hello', ['hello.c'], CCFLAGS='/MD', LIBS=['kernel32', 'user32', 'runtimeobject']) Example 1 - Output fragment: ... link /nologo /OUT:_build001\hello.exe kernel32.lib user32.lib runtimeobject.lib _build001\hello.obj LINK : fatal error LNK1104: cannot open file 'MSVCRT.lib' ... Example 2 - A Visual Studio 2022 build with user-defined script arguments and the script error policy set to issue a warning when msvc batch file errors are detected: env = environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['8.1', 'store', '-vcvars_ver=14.1'], MSVC_SCRIPTERROR_POLICY='warn') env.Program('hello', ['hello.c'], CCFLAGS='/MD', LIBS=['kernel32', 'user32', 'runtimeobject']) Example 2 - Output fragment: ... scons: warning: vc script errors detected: [ERROR:vcvars.bat] The UWP Application Platform requires a Windows 10 SDK. [ERROR:vcvars.bat] WindowsSdkDir = "C:\Program Files (x86)\Windows Kits\8.1\" [ERROR:vcvars.bat] host/target architecture is not supported : { x64 , x64 } ... link /nologo /OUT:_build001\hello.exe kernel32.lib user32.lib runtimeobject.lib _build001\hello.obj LINK : fatal error LNK1104: cannot open file 'MSVCRT.lib' Important usage details: &cv-MSVC_SCRIPTERROR_POLICY; must be passed as an argument to the &f-link-Environment; constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is loaded via the default tools list or via a tools list passed to the &f-link-Environment; constructor. Otherwise, &cv-MSVC_SCRIPTERROR_POLICY; must be set before the first msvc tool is loaded into the environment. Due to &scons; implementation details, not all Windows system environment variables are propagated to the environment in which the msvc batch file is executed. Depending on Visual Studio version and installation options, non-fatal msvc batch file error messages may be generated for ancillary tools which may not affect builds with the msvc compiler. For this reason, caution is recommended when setting the script error policy to raise an exception (e.g., 'Error').

Pass user-defined arguments to the Visual C++ batch file determined via autodetection. &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;) rather than &cv-MSVC_SCRIPT_ARGS; arguments. The valid values for &cv-MSVC_SCRIPT_ARGS; are: None, a string, or a list of strings. The &cv-MSVC_SCRIPT_ARGS; value is converted to a scalar string (i.e., "flattened"). The resulting scalar string, if not empty, is passed as an argument to the msvc batch file determined via autodetection subject to the validation conditions listed below. &cv-MSVC_SCRIPT_ARGS; is ignored when the value is None and when the result from argument conversion is an empty string. The validation conditions below do not apply. An exception is raised when any of the following conditions are satisfied: &cv-MSVC_SCRIPT_ARGS; is specified for Visual Studio 2013 and earlier. Multiple SDK version arguments (e.g., '10.0.20348.0') are specified in &cv-MSVC_SCRIPT_ARGS;. &cv-link-MSVC_SDK_VERSION; is specified and an SDK version argument (e.g., '10.0.20348.0') is specified in &cv-MSVC_SCRIPT_ARGS;. Multiple SDK version declarations via &cv-link-MSVC_SDK_VERSION; and &cv-MSVC_SCRIPT_ARGS; are not allowed. Multiple toolset version arguments (e.g., '-vcvars_ver=14.29') are specified in &cv-MSVC_SCRIPT_ARGS;. &cv-link-MSVC_TOOLSET_VERSION; is specified and a toolset version argument (e.g., '-vcvars_ver=14.29') is specified in &cv-MSVC_SCRIPT_ARGS;. Multiple toolset version declarations via &cv-link-MSVC_TOOLSET_VERSION; and &cv-MSVC_SCRIPT_ARGS; are not allowed. Multiple spectre library arguments (e.g., '-vcvars_spectre_libs=spectre') are specified in &cv-MSVC_SCRIPT_ARGS;. &cv-link-MSVC_SPECTRE_LIBS; is enabled and a spectre library argument (e.g., '-vcvars_spectre_libs=spectre') is specified in &cv-MSVC_SCRIPT_ARGS;. Multiple spectre library declarations via &cv-link-MSVC_SPECTRE_LIBS; and &cv-MSVC_SCRIPT_ARGS; are not allowed. Multiple UWP arguments (e.g., uwp or store) are specified in &cv-MSVC_SCRIPT_ARGS;. &cv-link-MSVC_UWP_APP; is enabled and a UWP argument (e.g., uwp or store) is specified in &cv-MSVC_SCRIPT_ARGS;. Multiple UWP declarations via &cv-link-MSVC_UWP_APP; and &cv-MSVC_SCRIPT_ARGS; are not allowed. Example 1 - A Visual Studio 2022 build with an SDK version and a toolset version specified with a string argument: env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS='10.0.20348.0 -vcvars_ver=14.29.30133') Example 2 - A Visual Studio 2022 build with an SDK version and a toolset version specified with a list argument: env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['10.0.20348.0', '-vcvars_ver=14.29.30133']) Important usage details: &cv-MSVC_SCRIPT_ARGS; must be passed as an argument to the &f-link-Environment; constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is loaded via the default tools list or via a tools list passed to the &f-link-Environment; constructor. Otherwise, &cv-MSVC_SCRIPT_ARGS; must be set before the first msvc tool is loaded into the environment. Other than checking for multiple declarations as described above, &cv-MSVC_SCRIPT_ARGS; arguments are not validated. Erroneous, inconsistent, and/or version incompatible &cv-MSVC_SCRIPT_ARGS; arguments are likely to result in build failures for reasons that are not readily apparent and may be difficult to diagnose. The burden is on the user to ensure that the arguments provided to the msvc batch file are valid, consistent and compatible with the version of msvc selected.

Build with a specific version of the Microsoft Software Development Kit (SDK). The valid values for &cv-MSVC_SDK_VERSION; are: None or a string containing the requested SDK version (e.g., '10.0.20348.0'). &cv-MSVC_SDK_VERSION; is ignored when the value is None and when the value is an empty string. The validation conditions below do not apply. An exception is raised when any of the following conditions are satisfied: &cv-MSVC_SDK_VERSION; is specified for Visual Studio 2013 and earlier. &cv-MSVC_SDK_VERSION; is specified and an SDK version argument is specified in &cv-link-MSVC_SCRIPT_ARGS;. Multiple SDK version declarations via &cv-MSVC_SDK_VERSION; and &cv-link-MSVC_SCRIPT_ARGS; are not allowed. The &cv-MSVC_SDK_VERSION; specified does not match any of the supported formats: '10.0.XXXXX.Y' [SDK 10.0] '8.1' [SDK 8.1] The system folder for the corresponding &cv-MSVC_SDK_VERSION; version is not found. The requested SDK version does not appear to be installed. The &cv-MSVC_SDK_VERSION; version does not appear to support the requested platform type (i.e., UWP or Desktop). The requested SDK version platform type components do not appear to be installed. The &cv-MSVC_SDK_VERSION; version is 8.1, the platform type is UWP, and the build tools selected are from Visual Studio 2017 and later (i.e., &cv-link-MSVC_VERSION; must be '14.0' or &cv-link-MSVC_TOOLSET_VERSION; must be '14.0'). Example 1 - A Visual Studio 2022 build with a specific Windows SDK version: env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.20348.0') Example 2 - A Visual Studio 2022 build with a specific SDK version for the Universal Windows Platform: env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.20348.0', MSVC_UWP_APP=True) Important usage details: &cv-MSVC_SDK_VERSION; must be passed as an argument to the &f-link-Environment; constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is loaded via the default tools list or via a tools list passed to the &f-link-Environment; constructor. Otherwise, &cv-MSVC_SDK_VERSION; must be set before the first msvc tool is loaded into the environment. Should a SDK 10.0 version be installed that does not follow the naming scheme above, the SDK version will need to be specified via &cv-link-MSVC_SCRIPT_ARGS; until the version number validation format can be extended. Should an exception be raised indicating that the SDK version is not found, verify that the requested SDK version is installed with the necessary platform type components. There is a known issue with the Microsoft libraries when the target architecture is ARM64 and a Windows 11 SDK (version '10.0.22000.0' and later) is used with the v141 build tools and older v142 toolsets (versions '14.28.29333' and earlier). Should build failures arise with these combinations of settings due to unresolved symbols in the Microsoft libraries, &cv-MSVC_SDK_VERSION; may be employed to specify a Windows 10 SDK (e.g., '10.0.20348.0') for the build.

Build with a specific Visual C++ toolset version. Specifying &cv-MSVC_TOOLSET_VERSION; does not affect the autodetection and selection of msvc instances. The &cv-MSVC_TOOLSET_VERSION; is applied after an msvc instance is selected. This could be the default version of msvc if &cv-link-MSVC_VERSION; is not specified. The valid values for &cv-MSVC_TOOLSET_VERSION; are: None or a string containing the requested toolset version (e.g., '14.29'). &cv-MSVC_TOOLSET_VERSION; is ignored when the value is None and when the value is an empty string. The validation conditions below do not apply. An exception is raised when any of the following conditions are satisfied: &cv-MSVC_TOOLSET_VERSION; is specified for Visual Studio 2015 and earlier. &cv-MSVC_TOOLSET_VERSION; is specified and a toolset version argument is specified in &cv-link-MSVC_SCRIPT_ARGS;. Multiple toolset version declarations via &cv-MSVC_TOOLSET_VERSION; and &cv-link-MSVC_SCRIPT_ARGS; are not allowed. The &cv-MSVC_TOOLSET_VERSION; specified does not match any of the supported formats: 'XX.Y' 'XX.YY' 'XX.YY.ZZZZZ' 'XX.YY.Z' to 'XX.YY.ZZZZ' [&scons; extension not directly supported by the msvc batch files and may be removed in the future] 'XX.YY.ZZ.N' [SxS format] 'XX.YY.ZZ.NN' [SxS format] The major msvc version prefix (i.e., 'XX.Y') of the &cv-MSVC_TOOLSET_VERSION; specified is for Visual Studio 2013 and earlier (e.g., '12.0'). The major msvc version prefix (i.e., 'XX.Y') of the &cv-MSVC_TOOLSET_VERSION; specified is greater than the msvc version selected (e.g., '99.0'). A system folder for the corresponding &cv-MSVC_TOOLSET_VERSION; version is not found. The requested toolset version does not appear to be installed. Toolset selection details: When &cv-MSVC_TOOLSET_VERSION; is not an SxS version number or a full toolset version number: the first toolset version, ranked in descending order, that matches the &cv-MSVC_TOOLSET_VERSION; prefix is selected. When &cv-MSVC_TOOLSET_VERSION; is specified using the major msvc version prefix (i.e., 'XX.Y') and the major msvc version is that of the latest release of Visual Studio, the selected toolset version may not be the same as the default Visual C++ toolset version. In the latest release of Visual Studio, the default Visual C++ toolset version is not necessarily the toolset with the largest version number. Example 1 - A default Visual Studio build with a partial toolset version specified: env = Environment(MSVC_TOOLSET_VERSION='14.2') Example 2 - A default Visual Studio build with a partial toolset version specified: env = Environment(MSVC_TOOLSET_VERSION='14.29') Example 3 - A Visual Studio 2022 build with a full toolset version specified: env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.29.30133') Example 4 - A Visual Studio 2022 build with an SxS toolset version specified: env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.29.16.11') Important usage details: &cv-MSVC_TOOLSET_VERSION; must be passed as an argument to the &f-link-Environment; constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is loaded via the default tools list or via a tools list passed to the &f-link-Environment; constructor. Otherwise, &cv-MSVC_TOOLSET_VERSION; must be set before the first msvc tool is loaded into the environment. The existence of the toolset host architecture and target architecture folders are not verified when &cv-MSVC_TOOLSET_VERSION; is specified which could result in build failures. The burden is on the user to ensure the requisite toolset target architecture build tools are installed.

Build with the spectre-mitigated Visual C++ libraries. The valid values for &cv-MSVC_SPECTRE_LIBS; are: True, False, or None. When &cv-MSVC_SPECTRE_LIBS; is enabled (i.e., True), the Visual C++ environment will include the paths to the spectre-mitigated implementations of the Microsoft Visual C++ libraries. An exception is raised when any of the following conditions are satisfied: &cv-MSVC_SPECTRE_LIBS; is enabled for Visual Studio 2015 and earlier. &cv-MSVC_SPECTRE_LIBS; is enabled and a spectre library argument is specified in &cv-link-MSVC_SCRIPT_ARGS;. Multiple spectre library declarations via &cv-MSVC_SPECTRE_LIBS; and &cv-link-MSVC_SCRIPT_ARGS; are not allowed. &cv-MSVC_SPECTRE_LIBS; is enabled and the platform type is UWP. There are no spectre-mitigated libraries for Universal Windows Platform (UWP) applications or components. Example - A Visual Studio 2022 build with spectre mitigated Visual C++ libraries: env = Environment(MSVC_VERSION='14.3', MSVC_SPECTRE_LIBS=True) Important usage details: &cv-MSVC_SPECTRE_LIBS; must be passed as an argument to the &f-link-Environment; constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is loaded via the default tools list or via a tools list passed to the &f-link-Environment; constructor. Otherwise, &cv-MSVC_SPECTRE_LIBS; must be set before the first msvc tool is loaded into the environment. Additional compiler switches (e.g., /Qspectre) are necessary for including spectre mitigations when building user artifacts. Refer to the Visual Studio documentation for details. The existence of the spectre libraries host architecture and target architecture folders are not verified when &cv-MSVC_SPECTRE_LIBS; is enabled which could result in build failures. The burden is on the user to ensure the requisite libraries with spectre mitigations are installed.