path: root/SCons/Tool/msvc.xml

<?xml version="1.0"?>
<!--
SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
SPDX-License-Identifier: MIT
SPDX-FileType: DOCUMENTATION

This file is processed by the bin/SConsDoc.py module.
-->

<!DOCTYPE sconsdoc [
<!ENTITY % scons SYSTEM '../../doc/scons.mod'>
%scons;
<!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
%builders-mod;
<!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
%functions-mod;
<!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
%tools-mod;
<!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
%variables-mod;
]>

<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">

<tool name="msvc">
<summary>
<para>
Sets &consvars; for the &MSVC; compiler.
</para>
</summary>
<sets>
<item>CCDEPFLAGS</item>
<item>CCPDBFLAGS</item>
<item>CCPCHFLAGS</item>
<item><!--CCCOMFLAGS--></item>
<item>CC</item>
<item>CCFLAGS</item>
<item>CFLAGS</item>
<item>CCCOM</item>
<item>SHCC</item>
<item>SHCCFLAGS</item>
<item>SHCFLAGS</item>
<item>SHCCCOM</item>
<item>CXX</item>
<item>CXXFLAGS</item>
<item>CXXCOM</item>
<item>SHCXX</item>
<item>SHCXXFLAGS</item>
<item>SHCXXCOM</item>
<item>CPPDEFPREFIX</item>
<item>CPPDEFSUFFIX</item>
<item>INCPREFIX</item>
<item>INCSUFFIX</item>
<item><!--STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME--></item>
<item>RC</item>
<item>RCFLAGS</item>
<item>RCCOM</item>
<item>BUILDERS</item>
<item>OBJPREFIX</item>
<item>OBJSUFFIX</item>
<item>SHOBJPREFIX</item>
<item>SHOBJSUFFIX</item>
<item>CFILESUFFIX</item>
<item>CXXFILESUFFIX</item>
<item>PCHPDBFLAGS</item>
<item>PCHCOM</item>
</sets>
<uses>
<item>CCCOMSTR</item>
<item>SHCCCOMSTR</item>
<item>CXXCOMSTR</item>
<item>SHCXXCOMSTR</item>
<item>PCH</item>
<item>PCHSTOP</item>
<item>PDB</item>
<item>MSVC_VERSION</item>
<item>MSVC_USE_SCRIPT</item>
<item>MSVC_USE_SCRIPT_ARGS</item>
<item>MSVC_USE_SETTINGS</item>
<item>MSVC_NOTFOUND_POLICY</item>
<item>MSVC_SCRIPTERROR_POLICY</item>
<item>MSVC_SCRIPT_ARGS</item>
<item>MSVC_SDK_VERSION</item>
<item>MSVC_TOOLSET_VERSION</item>
<item>MSVC_SPECTRE_LIBS</item>

</uses>
</tool>

<builder name="PCH">
<summary>
<para>
Builds a &MSVC; precompiled header.
Calling this builder
returns a list of two target nodes: the PCH as the first element,
and the object file as the second element.
Normally the object file is ignored.
The &b-PCH; builder is generally used in
conjunction with the &cv-link-PCH; &consvar; to force object files to use
the precompiled header:
</para>

<example_commands>
env['PCH'] = env.PCH('StdAfx.cpp')[0]
</example_commands>

<note>
<para>
This builder is specific to the PCH implementation in  &MSVC;.
Other compiler chains also implement precompiled header support,
but &b-PCH; does not work with them at this time.
As a result, the builder is only generated into the
construction environment when
&MSVC; is being used as the compiler.
</para>
<para>
The builder only works correctly in a C++ project.
The Microsoft implementation distinguishes between
precompiled headers from C and C++.
Use of the builder will cause the PCH generation to happen with a flag
that tells <application>cl.exe</application> all of the
files are C++ files; if that PCH file is then supplied when
compiling a C source file,
<application>cl.exe</application> will fail the build with
a compatibility violation.
</para>
<para>
If possible, arrange the project so that a
C++ source file passed to the &b-PCH; builder
is not also included in the list of sources
to be otherwise compiled in the project.
&SCons; will correctly track that file in the dependency tree
as a result of the &b-PCH; call,
and (for MSVC 11.0 and greater) automatically add the
corresponding object file to the link line.
If the source list is automatically generated,
for example using the &f-link-Glob; function,
it may be necessary to remove that file from the list.
</para>
</note>
</summary>
</builder>

<builder name="RES">
<summary>
<para>
Builds a &MSVC; resource file.
This builder method is only provided
when &MSVC; or MinGW is being used as the compiler. The
<filename>.res</filename>
(or
<filename>.o</filename>
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:
</para>

<example_commands>
env.RES('resource.rc')
</example_commands>
</summary>
</builder>

<cvar name="CCPCHFLAGS">
<summary>
<para>
Options added to the compiler command line
to support building with precompiled headers.
The default value expands expands to the appropriate
&MSVC; command-line options
when the &cv-link-PCH; &consvar; is set.
</para>
</summary>
</cvar>

<cvar name="CCPDBFLAGS">
<summary>
<para>
Options added to the compiler command line
to support storing debugging information in a
&MSVC; PDB file.
The default value expands expands to appropriate
&MSVC; command-line options
when the &cv-link-PDB; &consvar; is set.
</para>

<para>
The &MSVC; compiler option that &SCons; uses by default
to generate PDB information is <option>/Z7</option>.
This works correctly with parallel (<option>-j</option>) 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 <option>/Zi</option> instead may yield improved
link-time performance,
although parallel builds will no longer work.
</para>

<para>
You can generate PDB files with the <option>/Zi</option>
switch by overriding the default &cv-link-CCPDBFLAGS; variable as follows:
</para>

<example_commands>
env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
</example_commands>

<para>
An alternative would be to use the <option>/Zi</option>
to put the debugging information in a separate <filename>.pdb</filename>
file for each object file by overriding
the &cv-link-CCPDBFLAGS; variable as follows:
</para>

<example_commands>
env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
</example_commands>
</summary>
</cvar>

<cvar name="MSVC_BATCH">
<summary>
<para>
When set to any true value,
specifies that &SCons; should batch
compilation of object files
when calling the &MSVC; 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 &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; &consvar;).
Any compilations where the object (target) file base name
(minus the <filename>.obj</filename>)
does not match the source file base name
will be compiled separately.
</para>
</summary>
</cvar>

<cvar name="PCH">
<summary>
<para>
A node for the &MSVC; precompiled header that will be
used when compiling object files.
This variable is ignored by tools other than &MSVC;.
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.
Examples:
</para>

<example_commands>
env['PCH'] = File('StdAfx.pch')
env['PCH'] = env.PCH('pch.cc')[0]
</example_commands>
</summary>
</cvar>

<cvar name="PCHCOM">
<summary>
<para>
The command line used by the
&b-link-PCH;
builder to generated a precompiled header.
</para>
</summary>
</cvar>

<cvar name="PCHCOMSTR">
<summary>
<para>
The string displayed when generating a precompiled header.
If not set, then &cv-link-PCHCOM; (the command line) is displayed.
</para>
</summary>
</cvar>

<cvar name="PCHPDBFLAGS">
<summary>
<para>
A &consvar; that, when expanded,
adds the <option>/yD</option> flag to the command line
only if the &cv-link-PDB; &consvar; is set.
</para>
</summary>
</cvar>

<cvar name="PCHSTOP">
<summary>
<para>
This variable specifies how much of a source file is precompiled. This
variable is ignored by tools other than &MSVC;, or when
the PCH variable is not being used. When this variable is defined, 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:
</para>

<example_commands>
env['PCHSTOP'] = 'StdAfx.h'
</example_commands>
</summary>
</cvar>

<cvar name="RC">
<summary>
<para>
The resource compiler used to build
a &MSVC; resource file.
</para>
</summary>
</cvar>

<cvar name="RCCOM">
<summary>
<para>
The command line used to build
a &MSVC; resource file.
</para>
</summary>
</cvar>

<cvar name="RCCOMSTR">
<summary>
<para>
The string displayed when invoking the resource compiler
to build a &MSVC; resource file.
If this is not set, then &cv-link-RCCOM; (the command line) is displayed.
</para>
</summary>
</cvar>

<cvar name="RCFLAGS">
<summary>
<para>
The flags passed to the resource compiler by the &b-link-RES; builder.
</para>
</summary>
</cvar>

<cvar name="RCINCFLAGS">
<summary>
<para>
An automatically-generated &consvar;
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;.
</para>
</summary>
</cvar>

<cvar name="RCINCPREFIX">
<summary>
<para>
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; &consvar;
when the &cv-link-RCINCFLAGS; variable is expanded.
</para>
</summary>
</cvar>

<cvar name="RCINCSUFFIX">
<summary>
<para>
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; &consvar;
when the &cv-link-RCINCFLAGS; variable is expanded.
</para>
</summary>
</cvar>

<cvar name="MSVC_VERSION">
<summary>
<para>
A string to select the preferred  version of &MSVC;.
If the specified version is unavailable and/or unknown to &SCons;,
a warning is issued showing the versions actually discovered,
and the build will eventually fail indicating a missing compiler binary.
If &cv-MSVC_VERSION; is not set, &SCons; will (by default) select the
latest version of &MSVC; installed on your system
(excluding any preview versions).
</para>

<note>
  <para>
    In order to take effect, &cv-MSVC_VERSION; must be set before
    the initial &MSVC; compiler discovery takes place.
    Discovery happens, at the latest, during the first call to the
    &f-link-Environment; function, unless a <parameter>tools</parameter>
    list is specified which excludes the entire &MSVC; toolchain -
    that is, omits <literal>"defaults"</literal>
    and any specific tool module that refers to parts of the toolchain
    (&t-link-msvc;, &t-link-mslink;, &t-link-masm;, &t-link-midl;
    and &t-link-msvs;). In this case, detection is deferred until
    any one of those tool modules is invoked manually.
    The following two examples illustrate this:
  </para>

  <programlisting>
# MSVC_VERSION set as Environment is created
env = Environment(MSVC_VERSION='14.2')

# Initialization deferred with empty tools, triggered manually
env = Environment(tools=[])
env['MSVC_VERSION'] = '14.2
env.Tool('msvc')
env.Tool('mslink')
env.Tool('msvs')
  </programlisting>
</note>

<para>
The valid values for &cv-MSVC_VERSION; represent major versions
of the compiler, except that versions ending in <literal>Exp</literal>
refer to "Express" or "Express for Desktop" Visual Studio editions.
Values that do not look like a valid compiler version
<emphasis>string</emphasis> are not supported.
</para>

<para>
The following table shows the correspondence
of &cv-MSVC_VERSION; values to various version indicators
('x' is used as a placeholder for
a single digit that can vary).
</para>

<informaltable>
  <tgroup cols="5">
    <colspec align="left" />
    <colspec align="center" />
    <colspec align="center" />
    <colspec align="left" />
    <colspec align="center" />
    <thead>
      <row>
        <entry> SCons Key </entry>
        <entry> <literallayout>
Visual C++
Version </literallayout></entry>
        <entry> <literal>_MSVC_VER</literal> </entry>
        <entry> Visual Studio Product </entry>
        <!--entry> <literallayout>
Visual Studio
Product </literallayout></entry-->
        <entry> <literallayout>
MSBuild /
Visual Studio </literallayout></entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry> <literal>"14.3"</literal> </entry>
        <entry> 14.3x </entry>
        <entry> 193x </entry>
        <entry> Visual Studio 2022 </entry>
        <entry> 17.x, 17.1x </entry>
      </row>
      <row>
        <entry> <literal>"14.2"</literal> </entry>
        <entry> 14.2x </entry>
        <entry> 192x </entry>
        <entry> Visual Studio 2019 </entry>
        <entry> 16.x, 16.1x </entry>
      </row>
      <row>
        <entry> <literal>"14.1"</literal> </entry>
        <entry> 14.1 or 14.1x </entry>
        <entry> 191x </entry>
        <entry> Visual Studio 2017 </entry>
        <entry> 15.x </entry>
      </row>
      <row>
        <entry> <literal>"14.1Exp"</literal> </entry>
        <entry> 14.1 or 14.1x </entry>
        <entry> 191x </entry>
        <entry> Visual Studio 2017 Express </entry>
        <entry> 15.x </entry>
      </row>
      <row>
        <entry> <literal>"14.0"</literal> </entry>
        <entry> 14.0 </entry>
        <entry> 1900 </entry>
        <entry> Visual Studio 2015 </entry>
        <entry> 14.0 </entry>
      </row>
      <row>
        <entry> <literal>"14.0Exp"</literal> </entry>
        <entry> 14.0 </entry>
        <entry> 1900 </entry>
        <entry> Visual Studio 2015 Express </entry>
        <entry> 14.0 </entry>
      </row>
      <row>
        <entry> <literal>"12.0"</literal> </entry>
        <entry> 12.0 </entry>
        <entry> 1800 </entry>
        <entry> Visual Studio 2013 </entry>
        <entry> 12.0 </entry>
      </row>
      <row>
        <entry> <literal>"12.0Exp"</literal> </entry>
        <entry> 12.0 </entry>
        <entry> 1800 </entry>
        <entry> Visual Studio 2013 Express </entry>
        <entry> 12.0 </entry>
      </row>
      <row>
        <entry> <literal>"11.0"</literal> </entry>
        <entry> 11.0 </entry>
        <entry> 1700 </entry>
        <entry> Visual Studio 2012 </entry>
        <entry> 11.0 </entry>
      </row>
      <row>
        <entry> <literal>"11.0Exp"</literal> </entry>
        <entry> 11.0 </entry>
        <entry> 1700 </entry>
        <entry> Visual Studio 2012 Express </entry>
        <entry> 11.0 </entry>
      </row>
      <row>
        <entry> <literal>"10.0"</literal> </entry>
        <entry> 10.0 </entry>
        <entry> 1600 </entry>
        <entry> Visual Studio 2010 </entry>
        <entry> 10.0 </entry>
      </row>
      <row>
        <entry> <literal>"10.0Exp"</literal> </entry>
        <entry> 10.0 </entry>
        <entry> 1600 </entry>
        <entry> Visual C++ Express 2010 </entry>
        <entry> 10.0 </entry>
      </row>
      <row>
        <entry> <literal>"9.0"</literal> </entry>
        <entry> 9.0 </entry>
        <entry> 1500 </entry>
        <entry> Visual Studio 2008 </entry>
        <entry> 9.0 </entry>
      </row>
      <row>
        <entry> <literal>"9.0Exp"</literal> </entry>
        <entry> 9.0 </entry>
        <entry> 1500 </entry>
        <entry> Visual C++ Express 2008 </entry>
        <entry> 9.0 </entry>
      </row>
      <row>
        <entry> <literal>"8.0"</literal> </entry>
        <entry> 8.0 </entry>
        <entry> 1400 </entry>
        <entry> Visual Studio 2005 </entry>
        <entry> 8.0 </entry>
      </row>
      <row>
        <entry> <literal>"8.0Exp"</literal> </entry>
        <entry> 8.0 </entry>
        <entry> 1400 </entry>
        <entry> Visual C++ Express 2005 </entry>
        <entry> 8.0 </entry>
      </row>
      <row>
        <entry> <literal>"7.1"</literal> </entry>
        <entry> 7.1 </entry>
        <entry> 1300 </entry>
        <entry> Visual Studio .NET 2003 </entry>
        <entry> 7.1 </entry>
      </row>
      <row>
        <entry> <literal>"7.0"</literal> </entry>
        <entry> 7.0 </entry>
        <entry> 1200 </entry>
        <entry> Visual Studio .NET 2002 </entry>
        <entry> 7.0 </entry>
      </row>
      <row>
        <entry> <literal>"6.0"</literal> </entry>
        <entry> 6.0 </entry>
        <entry> 1100 </entry>
        <entry> Visual Studio 6.0 </entry>
        <entry> 6.0 </entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>

<note>
  <itemizedlist>

    <listitem><para>
    It is not necessary to install a Visual Studio IDE
    to build with &SCons; (for example, you can install only
    Build Tools), but when a Visual Studio IDE is installed,
    additional builders such as &b-link-MSVSSolution; and
    &b-link-MSVSProject; become available and correspond to
    the specified versions.
    </para></listitem>

    <listitem><para>
    Versions ending in <literal>Exp</literal> refer to historical
    "Express" or "Express for Desktop" Visual Studio editions,
    which had feature limitations compared to the full editions.
    It is only necessary to specify the <literal>Exp</literal>
    suffix to select the express edition when both express and
    non-express editions of the same product are installed
    simultaneously. The <literal>Exp</literal> suffix is unnecessary,
    but accepted, when only the express edition is installed.
    </para></listitem>
  </itemizedlist>
</note>

<para>
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;.
</para>

</summary>
</cvar>

<cvar name="MSVC_USE_SCRIPT">
<summary>
<para>
Use a batch script to set up the &MSVC; compiler.
</para>

<para>
If set to the name of a Visual Studio <filename>.bat</filename> file
(e.g. <filename>vcvars.bat</filename>),
&SCons; will run that batch file instead of the auto-detected one,
and extract the relevant variables from the result (typically
<envar>%INCLUDE%</envar>,
<envar>%LIB%</envar>, and
<envar>%PATH%</envar>) 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.
</para>

<para>
Setting
&cv-MSVC_USE_SCRIPT; to <constant>None</constant> bypasses the
Visual Studio autodetection entirely;
use this if you are running &SCons; in a Visual Studio <command>cmd</command>
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.
</para>
<para>
&cv-MSVC_USE_SCRIPT; ignores &cv-link-MSVC_VERSION; and &cv-link-TARGET_ARCH;.
</para>

<para><emphasis>Changed in version 4.4:</emphasis>
new &cv-link-MSVC_USE_SCRIPT_ARGS; provides a
way to pass arguments.
</para>

</summary>
</cvar>

<cvar name="MSVC_USE_SCRIPT_ARGS">
<summary>
<para>
Provides arguments passed to the script &cv-link-MSVC_USE_SCRIPT;.
</para>

<para><emphasis>New in version 4.4</emphasis></para>

</summary>
</cvar>

<cvar name="MSVC_USE_SETTINGS">
<summary>
<para>
Use a dictionary to set up the &MSVC; compiler.
</para>

<para>
&cv-MSVC_USE_SETTINGS; is ignored when &cv-link-MSVC_USE_SCRIPT; is defined
and/or when &cv-MSVC_USE_SETTINGS; is set to <constant>None</constant>.
</para>

<para>
The dictionary is used to populate the environment with the relevant variables
(typically <envar>%INCLUDE%</envar>, <envar>%LIB%</envar>, and <envar>%PATH%</envar>)
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 <constant>None</constant>.
</para>

<para>
Here is an example of configuring a build environment using the &MSVC; compiler
included in the Microsoft SDK on a 64-bit host and building for a 64-bit architecture:
<programlisting>
# 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)
</programlisting>
</para>

<para>
Important usage details:
<itemizedlist>

<listitem><para>
&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.
</para></listitem>

<listitem><para>
<emphasis>
The dictionary content requirements are based on the internal msvc implementation and
therefore may change at any time.
</emphasis>
The burden is on the user to ensure the dictionary contents are minimally sufficient to
ensure successful builds.
</para>

</listitem>

</itemizedlist>
</para>

<para><emphasis>New in version 4.4</emphasis></para>

</summary>
</cvar>

<!-- This has moved to Platform/Platform.xml to avoid duplication
<cvar name="HOST_ARCH">
<summary>
<para>
</para>
</summary>
</cvar>
-->

<!-- This has moved to Platform/Platform.xml to avoid duplication
<cvar name="TARGET_ARCH">
<summary>
<para>
</para>
</summary>
</cvar>
-->

<cvar name="MSVC_UWP_APP">
<summary>
<para>
Build with the Universal Windows Platform (UWP) application &MSVC; libraries.
</para>

<para>
The valid values for &cv-MSVC_UWP_APP; are: <literal>True</literal>,
<literal>'1'</literal>, <literal>False</literal>, <literal>'0'</literal>,
or <literal>None</literal>.
</para>

<para>
When &cv-MSVC_UWP_APP; is enabled (i.e., <literal>True</literal> or
<literal>'1'</literal>), the &MSVC; environment will be set up to point
to the Windows Store compatible libraries and &MSVC; 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.
<!-- This flag will only have an effect with Visual Studio 2015 or later. -->
<!-- This variable must be passed as an argument to the Environment()
constructor; setting it later has no effect. -->
</para>

<para>
An exception is raised when any of the following conditions are satisfied:
<itemizedlist>
<listitem><para>
&cv-MSVC_UWP_APP; is enabled for Visual Studio 2013 and earlier.
</para></listitem>
<listitem><para>
&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.
</para></listitem>
</itemizedlist>
</para>

<para>
Example - A Visual Studio 2022 build for the Universal Windows Platform:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_UWP_APP=True)
</example_commands>
</para>

<para>
Important usage details:
<itemizedlist>

<listitem><para>
&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.
</para></listitem>

<listitem><para>
<emphasis>
The existence of the UWP libraries is not verified when &cv-MSVC_UWP_APP; is enabled
which could result in build failures.
</emphasis>
The burden is on the user to ensure the requisite UWP libraries are installed.
</para></listitem>

</itemizedlist>
</para>

</summary>
</cvar>

<cvar name="VSWHERE">
<summary>
<para>
Specify the location of <command>vswhere.exe</command>.
</para>

<para>
    The <command>vswhere.exe</command> executable is distributed with
    Microsoft Visual Studio and Build Tools since the 2017 edition,
    but is also available as a standalone installation.
    It allows queries to obtain detailed information about
    installations of 2017 and later editions.
    &SCons; makes use of this information to determine
    the state of compiler support for those editions.
</para>
<para>
    Setting the &cv-VSWHERE; variable to the path to a specific
    <command>vswhere.exe</command> binary
    causes &SCons; to use that binary.
    If not set, &SCons; will search for one,
    looking in the following locations in order,
    using the first found
    (&cv-VSWHERE; is updated with the location):
</para>

<simplelist type="vert">
<member><literal>%ProgramFiles(x86)%\Microsoft Visual Studio\Installer</literal></member>
<member><literal>%ProgramFiles%\Microsoft Visual Studio\Installer</literal></member>
<member><literal>%ChocolateyInstall%\bin</literal></member>
<member><literal>%LOCALAPPDATA%\Microsoft\WinGet\Links</literal></member>
<member><literal>%USERPROFILE%\scoop\shims</literal></member>
<member><literal>%SCOOP%\shims</literal></member>
</simplelist>


<note>
  <para>
    In order to take effect, &cv-VSWHERE; must be set before
    the initial &MSVC; compiler discovery takes place.
    Discovery happens, at the latest, during the first call to the
    &f-link-Environment; function, unless a <parameter>tools</parameter>
    list is specified which excludes the entire &MSVC; toolchain -
    that is, omits <literal>"defaults"</literal>
    and any specific tool module that refers to parts of the toolchain
    (&t-link-msvc;, &t-link-mslink;, &t-link-masm;, &t-link-midl;
    and &t-link-msvs;). In this case, detection is deferred until
    any one of those tool modules is invoked manually.
    The following two examples illustrate this:
  </para>

  <programlisting>
# VSWHERE set as Environment is created
env = Environment(VSWHERE='c:/my/path/to/vswhere')

# Initialization deferred with empty tools, triggered manually
env = Environment(tools=[])
env['VSWHERE'] = r'c:/my/vswhere/install/location/vswhere.exe'
env.Tool('msvc')
env.Tool('mslink')
env.Tool('msvs')
  </programlisting>
</note>

</summary>
</cvar>

<cvar name="MSVC_NOTFOUND_POLICY">
<summary>
<para>
Specify the &scons; behavior when the &MSVC; compiler is not detected.
</para>

<para>
    The &cv-MSVC_NOTFOUND_POLICY; specifies the &scons; behavior when no msvc versions are detected or
    when the requested msvc version is not detected.
</para>

<para>
The valid values for &cv-MSVC_NOTFOUND_POLICY; and the corresponding &scons; behavior are:
</para>

<variablelist>

<varlistentry>
<term><parameter>'Error' or 'Exception'</parameter></term>
<listitem>
<para>
Raise an exception when no msvc versions are detected or when the requested msvc version is not detected.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><parameter>'Warning' or 'Warn'</parameter></term>
<listitem>
<para>
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).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><parameter>'Ignore' or 'Suppress'</parameter></term>
<listitem>
<para>
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).
</para>
</listitem>
</varlistentry>

</variablelist>

<para>
Note: in addition to the camel case values shown above, lower case and upper case values are accepted as well.
</para>

<para>
The &cv-MSVC_NOTFOUND_POLICY; is applied when any of the following conditions are satisfied:
<itemizedlist>
<listitem><para>
&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.
</para></listitem>
<listitem><para>
&cv-MSVC_VERSION; is specified, the default tools list is explicitly specified (e.g., <literal>tools=['default']</literal>),
and the default tools list contains one or more of the msvc tools.
</para></listitem>
<listitem><para>
A non-default tools list is specified that contains one or more of the msvc tools (e.g., <literal>tools=['msvc', 'mslink']</literal>).
</para></listitem>
</itemizedlist>
</para>

<para>
The &cv-MSVC_NOTFOUND_POLICY; is ignored when any of the following conditions are satisfied:
<itemizedlist>
<listitem><para>
&cv-MSVC_VERSION; is not specified and the default tools list is implicitly defined (i.e., the tools list is not specified).
</para></listitem>
<listitem><para>
&cv-MSVC_VERSION; is not specified and the default tools list is explicitly specified (e.g., <literal>tools=['default']</literal>).
</para></listitem>
<listitem><para>
A non-default tool list is specified that does not contain any of the msvc tools (e.g., <literal>tools=['mingw']</literal>).
</para></listitem>
</itemizedlist>
</para>

<para>
Important usage details:
<itemizedlist>

<listitem><para>
&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.
</para></listitem>

</itemizedlist>
</para>

<para>
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.
</para>

<para><emphasis>New in version 4.4</emphasis></para>

</summary>
</cvar>

<cvar name="MSVC_SCRIPTERROR_POLICY">
<summary>
<para>
Specify the &scons; behavior when &MSVC; batch file errors are detected.
</para>

<para>
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.
</para>
<para>
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 <emphasis>may</emphasis>
produce additional diagnostic information.
</para>

<para>
The valid values for &cv-MSVC_SCRIPTERROR_POLICY; and the corresponding &scons; behavior are:
</para>

<variablelist>

<varlistentry>
<term><parameter>'Error' or 'Exception'</parameter></term>
<listitem>
<para>
Raise an exception when msvc batch file errors are detected.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><parameter>'Warning' or 'Warn'</parameter></term>
<listitem>
<para>
Issue a warning when msvc batch file errors are detected.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><parameter>'Ignore' or 'Suppress'</parameter></term>
<listitem>
<para>
Suppress msvc batch file error messages.
</para>

<para><emphasis>New in version 4.4</emphasis></para>

</listitem>
</varlistentry>

</variablelist>

<para>
Note: in addition to the camel case values shown above, lower case and upper case values are accepted as well.
</para>

<para>
Example 1 - A Visual Studio 2022 build with user-defined script arguments:
<example_commands>
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_commands>
</para>

<para>
Example 1 - Output fragment:
<example_commands>
...
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_commands>
</para>

<para>
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:
<example_commands>
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_commands>
</para>

<para>
Example 2 - Output fragment:
<example_commands>
...
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'
</example_commands>
</para>

<para>
Important usage details:
<itemizedlist>

<listitem><para>
&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.
</para></listitem>

<listitem><para>
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., <literal>'Error'</literal>).
</para></listitem>

</itemizedlist>
</para>

<para><emphasis>New in version 4.4</emphasis></para>

</summary>
</cvar>

<cvar name="MSVC_SCRIPT_ARGS">
<summary>
<para>
Pass user-defined arguments to the &MSVC; batch file determined via autodetection.
</para>

<para>
&cv-MSVC_SCRIPT_ARGS; is available for msvc batch file arguments that do not have first-class support
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.
</para>

<para>
The valid values for &cv-MSVC_SCRIPT_ARGS; are: <literal>None</literal>, a string,
or a list of strings.
</para>

<para>
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.
</para>

<para>
&cv-MSVC_SCRIPT_ARGS; is ignored when the value is <literal>None</literal> and when the
result from argument conversion is an empty string.  The validation conditions below do not apply.
</para>

<para>
An exception is raised when any of the following conditions are satisfied:
<itemizedlist>

<listitem><para>
&cv-MSVC_SCRIPT_ARGS; is specified for Visual Studio 2013 and earlier.
</para></listitem>

<listitem><para>
Multiple SDK version arguments (e.g., <literal>'10.0.20348.0'</literal>) are specified
in &cv-MSVC_SCRIPT_ARGS;.
</para></listitem>

<listitem><para>
&cv-link-MSVC_SDK_VERSION; is specified and an SDK version argument
(e.g., <literal>'10.0.20348.0'</literal>) 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.
</para></listitem>

<listitem><para>
Multiple toolset version arguments (e.g., <literal>'-vcvars_ver=14.29'</literal>)
are specified in &cv-MSVC_SCRIPT_ARGS;.
</para></listitem>

<listitem><para>
&cv-link-MSVC_TOOLSET_VERSION; is specified and a toolset version argument
(e.g., <literal>'-vcvars_ver=14.29'</literal>) 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.
</para></listitem>

<listitem><para>
Multiple spectre library arguments (e.g., <literal>'-vcvars_spectre_libs=spectre'</literal>)
are specified in &cv-MSVC_SCRIPT_ARGS;.
</para></listitem>

<listitem><para>
&cv-link-MSVC_SPECTRE_LIBS; is enabled and a spectre library argument
(e.g., <literal>'-vcvars_spectre_libs=spectre'</literal>) 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.
</para></listitem>

<listitem><para>
Multiple UWP arguments (e.g., <literal>uwp</literal> or <literal>store</literal>) are specified
in &cv-MSVC_SCRIPT_ARGS;.
</para></listitem>

<listitem><para>
&cv-link-MSVC_UWP_APP; is enabled and a UWP argument (e.g., <literal>uwp</literal> or
<literal>store</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;. Multiple UWP declarations
via &cv-link-MSVC_UWP_APP; and &cv-MSVC_SCRIPT_ARGS; are not allowed.
</para></listitem>

</itemizedlist>
</para>

<para>
Example 1 - A Visual Studio 2022 build with an SDK version and a toolset version
specified with a string argument:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS='10.0.20348.0 -vcvars_ver=14.29.30133')
</example_commands>
</para>

<para>
Example 2 - A Visual Studio 2022 build with an SDK version and a toolset version
specified with a list argument:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['10.0.20348.0', '-vcvars_ver=14.29.30133'])
</example_commands>
</para>

<para>
Important usage details:
<itemizedlist>

<listitem><para>
&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.
</para></listitem>

<listitem><para>
Other than checking for multiple declarations as described above, &cv-MSVC_SCRIPT_ARGS; arguments
are not validated.
</para></listitem>

<listitem><para>
<emphasis>
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.
</emphasis>
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.
</para></listitem>

</itemizedlist>
</para>

<para><emphasis>New in version 4.4</emphasis></para>

</summary>
</cvar>

<cvar name="MSVC_SDK_VERSION">
<summary>
<para>
Build with a specific version of the Microsoft Software Development Kit (SDK).
</para>

<para>
The valid values for &cv-MSVC_SDK_VERSION; are: <literal>None</literal>
or a string containing the requested SDK version (e.g., <literal>'10.0.20348.0'</literal>).
</para>

<para>
&cv-MSVC_SDK_VERSION; is ignored when the value is <literal>None</literal> and when
the value is an empty string.  The validation conditions below do not apply.
</para>

<para>
An exception is raised when any of the following conditions are satisfied:
<itemizedlist>

<listitem><para>
&cv-MSVC_SDK_VERSION; is specified for Visual Studio 2013 and earlier.
</para></listitem>

<listitem><para>
&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.
</para></listitem>

<listitem><para>
The &cv-MSVC_SDK_VERSION; specified does not match any of the supported formats:
<itemizedlist>
<listitem><para>
<literal>'10.0.XXXXX.Y'</literal> [SDK 10.0]
</para></listitem>
<listitem><para>
<literal>'8.1'</literal> [SDK 8.1]
</para></listitem>
</itemizedlist>
</para></listitem>

<listitem><para>
The system folder for the corresponding &cv-MSVC_SDK_VERSION; version is not found.
The requested SDK version does not appear to be installed.
</para></listitem>

<listitem><para>
The &cv-MSVC_SDK_VERSION; version does not appear to support the requested platform
type (i.e., <literal>UWP</literal> or <literal>Desktop</literal>).  The requested SDK version
platform type components do not appear to be installed.
</para></listitem>

<listitem><para>
The &cv-MSVC_SDK_VERSION; version is <literal>8.1</literal>, the platform type is
<literal>UWP</literal>, 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').
</para></listitem>

</itemizedlist>
</para>

<para>
Example 1 - A Visual Studio 2022 build with a specific Windows SDK version:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.20348.0')
</example_commands>
</para>

<para>
Example 2 - A Visual Studio 2022 build with a specific SDK version for the Universal Windows Platform:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.20348.0', MSVC_UWP_APP=True)
</example_commands>
</para>

<para>
Important usage details:
<itemizedlist>

<listitem><para>
&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.
</para></listitem>

<listitem>
<para><emphasis>
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.
</emphasis></para>
</listitem>

<listitem><para>
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.
</para></listitem>

<listitem><para>
There is a known issue with the Microsoft libraries when the target architecture is
<literal>ARM64</literal> and a Windows 11 SDK (version <literal>'10.0.22000.0'</literal> and later) is used
with the <literal>v141</literal> build tools and older <literal>v142</literal> toolsets
(versions <literal>'14.28.29333'</literal> 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., <literal>'10.0.20348.0'</literal>) for the build.
</para></listitem>

</itemizedlist>
</para>

<para><emphasis>New in version 4.4</emphasis></para>

</summary>
</cvar>

<cvar name="MSVC_TOOLSET_VERSION">
<summary>
<para>
Build with a specific &MSVC; toolset version.
</para>

<para><emphasis>
Specifying &cv-MSVC_TOOLSET_VERSION; does not affect the autodetection and selection
of msvc instances. The &cv-MSVC_TOOLSET_VERSION; is applied <emphasis>after</emphasis>
an msvc instance is selected. This could be the default version of msvc if &cv-link-MSVC_VERSION;
is not specified.
</emphasis></para>

<para>
The valid values for &cv-MSVC_TOOLSET_VERSION; are: <literal>None</literal>
or a string containing the requested toolset version (e.g., <literal>'14.29'</literal>).
</para>

<para>
&cv-MSVC_TOOLSET_VERSION; is ignored when the value is <literal>None</literal> and when
the value is an empty string.  The validation conditions below do not apply.
</para>

<para>
An exception is raised when any of the following conditions are satisfied:
<itemizedlist>

<listitem><para>
&cv-MSVC_TOOLSET_VERSION; is specified for Visual Studio 2015 and earlier.
</para></listitem>

<listitem><para>
&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.
</para></listitem>

<listitem>
<para>
The &cv-MSVC_TOOLSET_VERSION; specified does not match any of the supported formats:
</para>

<itemizedlist>

<listitem><para>
<literal>'XX.Y'</literal>
</para></listitem>

<listitem><para>
<literal>'XX.YY'</literal>
</para></listitem>

<listitem><para>
<literal>'XX.YY.ZZZZZ'</literal>
</para></listitem>

<listitem><para>
<literal>'XX.YY.Z'</literal> to <literal>'XX.YY.ZZZZ'</literal>
<emphasis>
[&scons; extension not directly supported by the msvc batch files and may be removed in the future]
</emphasis>
</para></listitem>

<listitem><para>
<literal>'XX.YY.ZZ.N'</literal> [SxS format]
</para></listitem>

<listitem><para>
<literal>'XX.YY.ZZ.NN'</literal> [SxS format]
</para></listitem>

</itemizedlist>

</listitem>

<listitem><para>
The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the &cv-MSVC_TOOLSET_VERSION; specified
is for Visual Studio 2013 and earlier (e.g., <literal>'12.0'</literal>).
</para></listitem>

<listitem><para>
The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the &cv-MSVC_TOOLSET_VERSION; specified
is greater than the msvc version selected (e.g., <literal>'99.0'</literal>).
</para></listitem>

<listitem><para>
A system folder for the corresponding &cv-MSVC_TOOLSET_VERSION; version is not found.
The requested toolset version does not appear to be installed.
</para></listitem>

</itemizedlist>
</para>

<para>
Toolset selection details:
<itemizedlist>

<listitem><para>
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.
</para></listitem>

<listitem><para>
When &cv-MSVC_TOOLSET_VERSION; is specified using the major msvc version prefix
(i.e., <literal>'XX.Y'</literal>) 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 &MSVC; toolset version.
</para><para>
In the latest release of Visual Studio, the default &MSVC; toolset version is not necessarily the
toolset with the largest version number.
</para></listitem>

</itemizedlist>
</para>

<para>
Example 1 - A default Visual Studio build with a partial toolset version specified:
<example_commands>
env = Environment(MSVC_TOOLSET_VERSION='14.2')
</example_commands>
</para>

<para>
Example 2 - A default Visual Studio build with a partial toolset version specified:
<example_commands>
env = Environment(MSVC_TOOLSET_VERSION='14.29')
</example_commands>
</para>

<para>
Example 3 - A Visual Studio 2022 build with a full toolset version specified:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.29.30133')
</example_commands>
</para>

<para>
Example 4 - A Visual Studio 2022 build with an SxS toolset version specified:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.29.16.11')
</example_commands>
</para>

<para>
Important usage details:
<itemizedlist>

<listitem><para>
&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.
</para></listitem>

<listitem><para>
<emphasis>
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.
</emphasis>
The burden is on the user to ensure the requisite toolset target architecture build tools are installed.
</para></listitem>

</itemizedlist>
</para>

<para><emphasis>New in version 4.4</emphasis></para>

</summary>
</cvar>

<cvar name="MSVC_SPECTRE_LIBS">
<summary>
<para>
Build with the spectre-mitigated &MSVC; libraries.
</para>

<para>
The valid values for &cv-MSVC_SPECTRE_LIBS; are: <literal>True</literal>,
<literal>False</literal>, or <literal>None</literal>.
</para>

<para>
When &cv-MSVC_SPECTRE_LIBS; is enabled (i.e., <literal>True</literal>),
the &MSVC; environment will include the paths to the spectre-mitigated implementations
of the &MSVC; libraries.
</para>

<para>
An exception is raised when any of the following conditions are satisfied:
<itemizedlist>

<listitem><para>
&cv-MSVC_SPECTRE_LIBS; is enabled for Visual Studio 2015 and earlier.
</para></listitem>

<listitem><para>
&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.
</para></listitem>

<listitem><para>
&cv-MSVC_SPECTRE_LIBS; is enabled and the platform type is <literal>UWP</literal>. There
are no spectre-mitigated libraries for Universal Windows Platform (UWP) applications or
components.
</para></listitem>

</itemizedlist>
</para>

<para>
Example - A Visual Studio 2022 build with spectre mitigated &MSVC; libraries:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_SPECTRE_LIBS=True)
</example_commands>
</para>

<para>
Important usage details:
<itemizedlist>

<listitem><para>
&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.
</para></listitem>

<listitem><para>
Additional compiler switches (e.g., <literal>/Qspectre</literal>) are necessary for including
spectre mitigations when building user artifacts. Refer to the Visual Studio documentation for
details.
</para></listitem>

<listitem><para>
<emphasis>
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.
</emphasis>
The burden is on the user to ensure the requisite libraries with spectre mitigations are installed.
</para></listitem>

</itemizedlist>
</para>

<para><emphasis>New in version 4.4</emphasis></para>

</summary>
</cvar>

</sconsdoc>