SCons/Tool/msvc.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   4 SPDX-License-Identifier: MIT
   5 SPDX-FileType: DOCUMENTATION
   6
   7 This file is processed by the bin/SConsDoc.py module.
   8 -->
   9
  10 <!DOCTYPE sconsdoc [
  11 <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
  12 %scons;
  13 <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
  14 %builders-mod;
  15 <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
  16 %functions-mod;
  17 <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
  18 %tools-mod;
  19 <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
  20 %variables-mod;
  21 ]>
  22
  23 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  24           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  25           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  26
  27 <tool name="msvc">
  28 <summary>
  29 <para>
  30 Sets &consvars; for the &MSVC; compiler.
  31 </para>
  32 </summary>
  33 <sets>
  34 <item>CCDEPFLAGS</item>
  35 <item>CCPDBFLAGS</item>
  36 <item>CCPCHFLAGS</item>
  37 <item><!--CCCOMFLAGS--></item>
  38 <item>CC</item>
  39 <item>CCFLAGS</item>
  40 <item>CFLAGS</item>
  41 <item>CCCOM</item>
  42 <item>SHCC</item>
  43 <item>SHCCFLAGS</item>
  44 <item>SHCFLAGS</item>
  45 <item>SHCCCOM</item>
  46 <item>CXX</item>
  47 <item>CXXFLAGS</item>
  48 <item>CXXCOM</item>
  49 <item>SHCXX</item>
  50 <item>SHCXXFLAGS</item>
  51 <item>SHCXXCOM</item>
  52 <item>CPPDEFPREFIX</item>
  53 <item>CPPDEFSUFFIX</item>
  54 <item>INCPREFIX</item>
  55 <item>INCSUFFIX</item>
  56 <item><!--STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME--></item>
  57 <item>RC</item>
  58 <item>RCFLAGS</item>
  59 <item>RCCOM</item>
  60 <item>BUILDERS</item>
  61 <item>OBJPREFIX</item>
  62 <item>OBJSUFFIX</item>
  63 <item>SHOBJPREFIX</item>
  64 <item>SHOBJSUFFIX</item>
  65 <item>CFILESUFFIX</item>
  66 <item>CXXFILESUFFIX</item>
  67 <item>PCHPDBFLAGS</item>
  68 <item>PCHCOM</item>
  69 </sets>
  70 <uses>
  71 <item>CCCOMSTR</item>
  72 <item>SHCCCOMSTR</item>
  73 <item>CXXCOMSTR</item>
  74 <item>SHCXXCOMSTR</item>
  75 <item>PCH</item>
  76 <item>PCHSTOP</item>
  77 <item>PDB</item>
  78 <item>MSVC_VERSION</item>
  79 <item>MSVC_USE_SCRIPT</item>
  80 <item>MSVC_USE_SCRIPT_ARGS</item>
  81 <item>MSVC_USE_SETTINGS</item>
  82 <item>MSVC_NOTFOUND_POLICY</item>
  83 <item>MSVC_SCRIPTERROR_POLICY</item>
  84 <item>MSVC_SCRIPT_ARGS</item>
  85 <item>MSVC_SDK_VERSION</item>
  86 <item>MSVC_TOOLSET_VERSION</item>
  87 <item>MSVC_SPECTRE_LIBS</item>
  88
  89 </uses>
  90 </tool>
  91
  92 <builder name="PCH">
  93 <summary>
  94 <para>
  95 Builds a &MSVC; precompiled header.
  96 Calling this builder
  97 returns a list of two target nodes: the PCH as the first element,
  98 and the object file as the second element.
  99 Normally the object file is ignored.
 100 The &b-PCH; builder is generally used in
 101 conjunction with the &cv-link-PCH; &consvar; to force object files to use
 102 the precompiled header:
 103 </para>
 104
 105 <example_commands>
 106 env['PCH'] = env.PCH('StdAfx.cpp')[0]
 107 </example_commands>
 108
 109 <note>
 110 <para>
 111 This builder is specific to the PCH implementation in  &MSVC;.
 112 Other compiler chains also implement precompiled header support,
 113 but &b-PCH; does not work with them at this time.
 114 As a result, the builder is only generated into the
 115 construction environment when
 116 &MSVC; is being used as the compiler.
 117 </para>
 118 <para>
 119 The builder only works correctly in a C++ project.
 120 The Microsoft implementation distinguishes between
 121 precompiled headers from C and C++.
 122 Use of the builder will cause the PCH generation to happen with a flag
 123 that tells <application>cl.exe</application> all of the
 124 files are C++ files; if that PCH file is then supplied when
 125 compiling a C source file,
 126 <application>cl.exe</application> will fail the build with
 127 a compatibility violation.
 128 </para>
 129 <para>
 130 If possible, arrange the project so that a
 131 C++ source file passed to the &b-PCH; builder
 132 is not also included in the list of sources
 133 to be otherwise compiled in the project.
 134 &SCons; will correctly track that file in the dependency tree
 135 as a result of the &b-PCH; call,
 136 and (for MSVC 11.0 and greater) automatically add the
 137 corresponding object file to the link line.
 138 If the source list is automatically generated,
 139 for example using the &f-link-Glob; function,
 140 it may be necessary to remove that file from the list.
 141 </para>
 142 </note>
 143 </summary>
 144 </builder>
 145
 146 <builder name="RES">
 147 <summary>
 148 <para>
 149 Builds a &MSVC; resource file.
 150 This builder method is only provided
 151 when &MSVC; or MinGW is being used as the compiler. The
 152 <filename>.res</filename>
 153 (or
 154 <filename>.o</filename>
 155 for MinGW) suffix is added to the target name if no other suffix is given.
 156 The source
 157 file is scanned for implicit dependencies as though it were a C file.
 158 Example:
 159 </para>
 160
 161 <example_commands>
 162 env.RES('resource.rc')
 163 </example_commands>
 164 </summary>
 165 </builder>
 166
 167 <cvar name="CCPCHFLAGS">
 168 <summary>
 169 <para>
 170 Options added to the compiler command line
 171 to support building with precompiled headers.
 172 The default value expands expands to the appropriate
 173 &MSVC; command-line options
 174 when the &cv-link-PCH; &consvar; is set.
 175 </para>
 176 </summary>
 177 </cvar>
 178
 179 <cvar name="CCPDBFLAGS">
 180 <summary>
 181 <para>
 182 Options added to the compiler command line
 183 to support storing debugging information in a
 184 &MSVC; PDB file.
 185 The default value expands expands to appropriate
 186 &MSVC; command-line options
 187 when the &cv-link-PDB; &consvar; is set.
 188 </para>
 189
 190 <para>
 191 The &MSVC; compiler option that &SCons; uses by default
 192 to generate PDB information is <option>/Z7</option>.
 193 This works correctly with parallel (<option>-j</option>) builds
 194 because it embeds the debug information in the intermediate object files,
 195 as opposed to sharing a single PDB file between multiple object files.
 196 This is also the only way to get debug information
 197 embedded into a static library.
 198 Using the <option>/Zi</option> instead may yield improved
 199 link-time performance,
 200 although parallel builds will no longer work.
 201 </para>
 202
 203 <para>
 204 You can generate PDB files with the <option>/Zi</option>
 205 switch by overriding the default &cv-link-CCPDBFLAGS; variable as follows:
 206 </para>
 207
 208 <example_commands>
 209 env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
 210 </example_commands>
 211
 212 <para>
 213 An alternative would be to use the <option>/Zi</option>
 214 to put the debugging information in a separate <filename>.pdb</filename>
 215 file for each object file by overriding
 216 the &cv-link-CCPDBFLAGS; variable as follows:
 217 </para>
 218
 219 <example_commands>
 220 env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
 221 </example_commands>
 222 </summary>
 223 </cvar>
 224
 225 <cvar name="MSVC_BATCH">
 226 <summary>
 227 <para>
 228 When set to any true value,
 229 specifies that &SCons; should batch
 230 compilation of object files
 231 when calling the &MSVC; compiler.
 232 All compilations of source files from the same source directory
 233 that generate target files in a same output directory
 234 and were configured in &SCons; using the same &consenv;
 235 will be built in a single call to the compiler.
 236 Only source files that have changed since their
 237 object files were built will be passed to each compiler invocation
 238 (via the &cv-link-CHANGED_SOURCES; &consvar;).
 239 Any compilations where the object (target) file base name
 240 (minus the <filename>.obj</filename>)
 241 does not match the source file base name
 242 will be compiled separately.
 243 </para>
 244 </summary>
 245 </cvar>
 246
 247 <cvar name="PCH">
 248 <summary>
 249 <para>
 250 A node for the &MSVC; precompiled header that will be
 251 used when compiling object files.
 252 This variable is ignored by tools other than &MSVC;.
 253 When this variable is
 254 defined, &SCons; will add options to the compiler command line to
 255 cause it to use the precompiled header, and will also set up the
 256 dependencies for the PCH file.
 257 Examples:
 258 </para>
 259
 260 <example_commands>
 261 env['PCH'] = File('StdAfx.pch')
 262 env['PCH'] = env.PCH('pch.cc')[0]
 263 </example_commands>
 264 </summary>
 265 </cvar>
 266
 267 <cvar name="PCHCOM">
 268 <summary>
 269 <para>
 270 The command line used by the
 271 &b-link-PCH;
 272 builder to generated a precompiled header.
 273 </para>
 274 </summary>
 275 </cvar>
 276
 277 <cvar name="PCHCOMSTR">
 278 <summary>
 279 <para>
 280 The string displayed when generating a precompiled header.
 281 If not set, then &cv-link-PCHCOM; (the command line) is displayed.
 282 </para>
 283 </summary>
 284 </cvar>
 285
 286 <cvar name="PCHPDBFLAGS">
 287 <summary>
 288 <para>
 289 A &consvar; that, when expanded,
 290 adds the <option>/yD</option> flag to the command line
 291 only if the &cv-link-PDB; &consvar; is set.
 292 </para>
 293 </summary>
 294 </cvar>
 295
 296 <cvar name="PCHSTOP">
 297 <summary>
 298 <para>
 299 This variable specifies how much of a source file is precompiled. This
 300 variable is ignored by tools other than &MSVC;, or when
 301 the PCH variable is not being used. When this variable is defined, it
 302 must be a string that is the name of the header that
 303 is included at the end of the precompiled portion of the source files, or
 304 the empty string if the "#pragma hrdstop" construct is being used:
 305 </para>
 306
 307 <example_commands>
 308 env['PCHSTOP'] = 'StdAfx.h'
 309 </example_commands>
 310 </summary>
 311 </cvar>
 312
 313 <cvar name="RC">
 314 <summary>
 315 <para>
 316 The resource compiler used to build
 317 a &MSVC; resource file.
 318 </para>
 319 </summary>
 320 </cvar>
 321
 322 <cvar name="RCCOM">
 323 <summary>
 324 <para>
 325 The command line used to build
 326 a &MSVC; resource file.
 327 </para>
 328 </summary>
 329 </cvar>
 330
 331 <cvar name="RCCOMSTR">
 332 <summary>
 333 <para>
 334 The string displayed when invoking the resource compiler
 335 to build a &MSVC; resource file.
 336 If this is not set, then &cv-link-RCCOM; (the command line) is displayed.
 337 </para>
 338 </summary>
 339 </cvar>
 340
 341 <cvar name="RCFLAGS">
 342 <summary>
 343 <para>
 344 The flags passed to the resource compiler by the &b-link-RES; builder.
 345 </para>
 346 </summary>
 347 </cvar>
 348
 349 <cvar name="RCINCFLAGS">
 350 <summary>
 351 <para>
 352 An automatically-generated &consvar;
 353 containing the command-line options
 354 for specifying directories to be searched
 355 by the resource compiler.
 356 The value of &cv-RCINCFLAGS; is created
 357 by respectively prepending and appending
 358 &cv-link-RCINCPREFIX; and &cv-link-RCINCSUFFIX;
 359 to the beginning and end
 360 of each directory in &cv-link-CPPPATH;.
 361 </para>
 362 </summary>
 363 </cvar>
 364
 365 <cvar name="RCINCPREFIX">
 366 <summary>
 367 <para>
 368 The prefix (flag) used to specify an include directory
 369 on the resource compiler command line.
 370 This will be prepended to the beginning of each directory
 371 in the &cv-link-CPPPATH; &consvar;
 372 when the &cv-link-RCINCFLAGS; variable is expanded.
 373 </para>
 374 </summary>
 375 </cvar>
 376
 377 <cvar name="RCINCSUFFIX">
 378 <summary>
 379 <para>
 380 The suffix used to specify an include directory
 381 on the resource compiler command line.
 382 This will be appended to the end of each directory
 383 in the &cv-link-CPPPATH; &consvar;
 384 when the &cv-link-RCINCFLAGS; variable is expanded.
 385 </para>
 386 </summary>
 387 </cvar>
 388
 389 <cvar name="MSVC_VERSION">
 390 <summary>
 391 <para>
 392 A string to select the preferred  version of &MSVC;.
 393 If the specified version is unavailable and/or unknown to &SCons;,
 394 a warning is issued showing the versions actually discovered,
 395 and the build will eventually fail indicating a missing compiler binary.
 396 If &cv-MSVC_VERSION; is not set, &SCons; will (by default) select the
 397 latest version of &MSVC; installed on your system
 398 (excluding any preview versions).
 399 </para>
 400
 401 <note>
 402   <para>
 403     In order to take effect, &cv-MSVC_VERSION; must be set before
 404     the initial &MSVC; compiler discovery takes place.
 405     Discovery happens, at the latest, during the first call to the
 406     &f-link-Environment; function, unless a <parameter>tools</parameter>
 407     list is specified which excludes the entire &MSVC; toolchain -
 408     that is, omits <literal>"defaults"</literal>
 409     and any specific tool module that refers to parts of the toolchain
 410     (&t-link-msvc;, &t-link-mslink;, &t-link-masm;, &t-link-midl;
 411     and &t-link-msvs;). In this case, detection is deferred until
 412     any one of those tool modules is invoked manually.
 413     The following two examples illustrate this:
 414   </para>
 415
 416   <programlisting>
 417 # MSVC_VERSION set as Environment is created
 418 env = Environment(MSVC_VERSION='14.2')
 419
 420 # Initialization deferred with empty tools, triggered manually
 421 env = Environment(tools=[])
 422 env['MSVC_VERSION'] = '14.2
 423 env.Tool('msvc')
 424 env.Tool('mslink')
 425 env.Tool('msvs')
 426   </programlisting>
 427 </note>
 428
 429 <para>
 430 The valid values for &cv-MSVC_VERSION; represent major versions
 431 of the compiler, except that versions ending in <literal>Exp</literal>
 432 refer to "Express" or "Express for Desktop" Visual Studio editions.
 433 Values that do not look like a valid compiler version
 434 <emphasis>string</emphasis> are not supported.
 435 </para>
 436
 437 <para>
 438 The following table shows the correspondence
 439 of &cv-MSVC_VERSION; values to various version indicators
 440 ('x' is used as a placeholder for
 441 a single digit that can vary).
 442 </para>
 443
 444 <informaltable>
 445   <tgroup cols="5">
 446     <colspec align="left" />
 447     <colspec align="center" />
 448     <colspec align="center" />
 449     <colspec align="left" />
 450     <colspec align="center" />
 451     <thead>
 452       <row>
 453         <entry> SCons Key </entry>
 454         <entry> <literallayout>
 455 Visual C++
 456 Version </literallayout></entry>
 457         <entry> <literal>_MSVC_VER</literal> </entry>
 458         <entry> Visual Studio Product </entry>
 459         <!--entry> <literallayout>
 460 Visual Studio
 461 Product </literallayout></entry-->
 462         <entry> <literallayout>
 463 MSBuild /
 464 Visual Studio </literallayout></entry>
 465       </row>
 466     </thead>
 467     <tbody>
 468       <row>
 469         <entry> <literal>"14.3"</literal> </entry>
 470         <entry> 14.3x </entry>
 471         <entry> 193x </entry>
 472         <entry> Visual Studio 2022 </entry>
 473         <entry> 17.x, 17.1x </entry>
 474       </row>
 475       <row>
 476         <entry> <literal>"14.2"</literal> </entry>
 477         <entry> 14.2x </entry>
 478         <entry> 192x </entry>
 479         <entry> Visual Studio 2019 </entry>
 480         <entry> 16.x, 16.1x </entry>
 481       </row>
 482       <row>
 483         <entry> <literal>"14.1"</literal> </entry>
 484         <entry> 14.1 or 14.1x </entry>
 485         <entry> 191x </entry>
 486         <entry> Visual Studio 2017 </entry>
 487         <entry> 15.x </entry>
 488       </row>
 489       <row>
 490         <entry> <literal>"14.1Exp"</literal> </entry>
 491         <entry> 14.1 or 14.1x </entry>
 492         <entry> 191x </entry>
 493         <entry> Visual Studio 2017 Express </entry>
 494         <entry> 15.x </entry>
 495       </row>
 496       <row>
 497         <entry> <literal>"14.0"</literal> </entry>
 498         <entry> 14.0 </entry>
 499         <entry> 1900 </entry>
 500         <entry> Visual Studio 2015 </entry>
 501         <entry> 14.0 </entry>
 502       </row>
 503       <row>
 504         <entry> <literal>"14.0Exp"</literal> </entry>
 505         <entry> 14.0 </entry>
 506         <entry> 1900 </entry>
 507         <entry> Visual Studio 2015 Express </entry>
 508         <entry> 14.0 </entry>
 509       </row>
 510       <row>
 511         <entry> <literal>"12.0"</literal> </entry>
 512         <entry> 12.0 </entry>
 513         <entry> 1800 </entry>
 514         <entry> Visual Studio 2013 </entry>
 515         <entry> 12.0 </entry>
 516       </row>
 517       <row>
 518         <entry> <literal>"12.0Exp"</literal> </entry>
 519         <entry> 12.0 </entry>
 520         <entry> 1800 </entry>
 521         <entry> Visual Studio 2013 Express </entry>
 522         <entry> 12.0 </entry>
 523       </row>
 524       <row>
 525         <entry> <literal>"11.0"</literal> </entry>
 526         <entry> 11.0 </entry>
 527         <entry> 1700 </entry>
 528         <entry> Visual Studio 2012 </entry>
 529         <entry> 11.0 </entry>
 530       </row>
 531       <row>
 532         <entry> <literal>"11.0Exp"</literal> </entry>
 533         <entry> 11.0 </entry>
 534         <entry> 1700 </entry>
 535         <entry> Visual Studio 2012 Express </entry>
 536         <entry> 11.0 </entry>
 537       </row>
 538       <row>
 539         <entry> <literal>"10.0"</literal> </entry>
 540         <entry> 10.0 </entry>
 541         <entry> 1600 </entry>
 542         <entry> Visual Studio 2010 </entry>
 543         <entry> 10.0 </entry>
 544       </row>
 545       <row>
 546         <entry> <literal>"10.0Exp"</literal> </entry>
 547         <entry> 10.0 </entry>
 548         <entry> 1600 </entry>
 549         <entry> Visual C++ Express 2010 </entry>
 550         <entry> 10.0 </entry>
 551       </row>
 552       <row>
 553         <entry> <literal>"9.0"</literal> </entry>
 554         <entry> 9.0 </entry>
 555         <entry> 1500 </entry>
 556         <entry> Visual Studio 2008 </entry>
 557         <entry> 9.0 </entry>
 558       </row>
 559       <row>
 560         <entry> <literal>"9.0Exp"</literal> </entry>
 561         <entry> 9.0 </entry>
 562         <entry> 1500 </entry>
 563         <entry> Visual C++ Express 2008 </entry>
 564         <entry> 9.0 </entry>
 565       </row>
 566       <row>
 567         <entry> <literal>"8.0"</literal> </entry>
 568         <entry> 8.0 </entry>
 569         <entry> 1400 </entry>
 570         <entry> Visual Studio 2005 </entry>
 571         <entry> 8.0 </entry>
 572       </row>
 573       <row>
 574         <entry> <literal>"8.0Exp"</literal> </entry>
 575         <entry> 8.0 </entry>
 576         <entry> 1400 </entry>
 577         <entry> Visual C++ Express 2005 </entry>
 578         <entry> 8.0 </entry>
 579       </row>
 580       <row>
 581         <entry> <literal>"7.1"</literal> </entry>
 582         <entry> 7.1 </entry>
 583         <entry> 1300 </entry>
 584         <entry> Visual Studio .NET 2003 </entry>
 585         <entry> 7.1 </entry>
 586       </row>
 587       <row>
 588         <entry> <literal>"7.0"</literal> </entry>
 589         <entry> 7.0 </entry>
 590         <entry> 1200 </entry>
 591         <entry> Visual Studio .NET 2002 </entry>
 592         <entry> 7.0 </entry>
 593       </row>
 594       <row>
 595         <entry> <literal>"6.0"</literal> </entry>
 596         <entry> 6.0 </entry>
 597         <entry> 1100 </entry>
 598         <entry> Visual Studio 6.0 </entry>
 599         <entry> 6.0 </entry>
 600       </row>
 601     </tbody>
 602   </tgroup>
 603 </informaltable>
 604
 605 <note>
 606   <itemizedlist>
 607
 608     <listitem><para>
 609     It is not necessary to install a Visual Studio IDE
 610     to build with &SCons; (for example, you can install only
 611     Build Tools), but when a Visual Studio IDE is installed,
 612     additional builders such as &b-link-MSVSSolution; and
 613     &b-link-MSVSProject; become available and correspond to
 614     the specified versions.
 615     </para></listitem>
 616
 617     <listitem><para>
 618     Versions ending in <literal>Exp</literal> refer to historical
 619     "Express" or "Express for Desktop" Visual Studio editions,
 620     which had feature limitations compared to the full editions.
 621     It is only necessary to specify the <literal>Exp</literal>
 622     suffix to select the express edition when both express and
 623     non-express editions of the same product are installed
 624     simultaneously. The <literal>Exp</literal> suffix is unnecessary,
 625     but accepted, when only the express edition is installed.
 626     </para></listitem>
 627   </itemizedlist>
 628 </note>
 629
 630 <para>
 631 The compilation environment can be further or more precisely specified through the
 632 use of several other &consvars;: see the descriptions of
 633 &cv-link-MSVC_TOOLSET_VERSION;,
 634 &cv-link-MSVC_SDK_VERSION;,
 635 &cv-link-MSVC_USE_SCRIPT;,
 636 &cv-link-MSVC_USE_SCRIPT_ARGS;,
 637 and &cv-link-MSVC_USE_SETTINGS;.
 638 </para>
 639
 640 </summary>
 641 </cvar>
 642
 643 <cvar name="MSVC_USE_SCRIPT">
 644 <summary>
 645 <para>
 646 Use a batch script to set up the &MSVC; compiler.
 647 </para>
 648
 649 <para>
 650 If set to the name of a Visual Studio <filename>.bat</filename> file
 651 (e.g. <filename>vcvars.bat</filename>),
 652 &SCons; will run that batch file instead of the auto-detected one,
 653 and extract the relevant variables from the result (typically
 654 <envar>%INCLUDE%</envar>,
 655 <envar>%LIB%</envar>, and
 656 <envar>%PATH%</envar>) for supplying to the build.
 657 This can be useful to force the use of a compiler version that
 658 &SCons; does not detect.
 659 &cv-link-MSVC_USE_SCRIPT_ARGS; provides arguments passed to this script.
 660 </para>
 661
 662 <para>
 663 Setting
 664 &cv-MSVC_USE_SCRIPT; to <constant>None</constant> bypasses the
 665 Visual Studio autodetection entirely;
 666 use this if you are running &SCons; in a Visual Studio <command>cmd</command>
 667 window and importing the shell's environment variables - that
 668 is, if you are sure everything is set correctly already and
 669 you don't want &SCons; to change anything.
 670 </para>
 671 <para>
 672 &cv-MSVC_USE_SCRIPT; ignores &cv-link-MSVC_VERSION; and &cv-link-TARGET_ARCH;.
 673 </para>
 674
 675 <para><emphasis>Changed in version 4.4:</emphasis>
 676 new &cv-link-MSVC_USE_SCRIPT_ARGS; provides a
 677 way to pass arguments.
 678 </para>
 679
 680 </summary>
 681 </cvar>
 682
 683 <cvar name="MSVC_USE_SCRIPT_ARGS">
 684 <summary>
 685 <para>
 686 Provides arguments passed to the script &cv-link-MSVC_USE_SCRIPT;.
 687 </para>
 688
 689 <para><emphasis>New in version 4.4</emphasis></para>
 690
 691 </summary>
 692 </cvar>
 693
 694 <cvar name="MSVC_USE_SETTINGS">
 695 <summary>
 696 <para>
 697 Use a dictionary to set up the &MSVC; compiler.
 698 </para>
 699
 700 <para>
 701 &cv-MSVC_USE_SETTINGS; is ignored when &cv-link-MSVC_USE_SCRIPT; is defined
 702 and/or when &cv-MSVC_USE_SETTINGS; is set to <constant>None</constant>.
 703 </para>
 704
 705 <para>
 706 The dictionary is used to populate the environment with the relevant variables
 707 (typically <envar>%INCLUDE%</envar>, <envar>%LIB%</envar>, and <envar>%PATH%</envar>)
 708 for supplying to the build. This can be useful to force the use of a compiler environment
 709 that &SCons; does not configure correctly. This is an alternative to manually configuring
 710 the environment when bypassing Visual Studio autodetection entirely by setting
 711 &cv-link-MSVC_USE_SCRIPT; to <constant>None</constant>.
 712 </para>
 713
 714 <para>
 715 Here is an example of configuring a build environment using the &MSVC; compiler
 716 included in the Microsoft SDK on a 64-bit host and building for a 64-bit architecture:
 717 <programlisting>
 718 # Microsoft SDK 6.0 (MSVC 8.0): 64-bit host and 64-bit target
 719 msvc_use_settings = {
 720     "PATH": [
 721         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Bin\\x64",
 722         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin\\x64",
 723         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin",
 724         "C:\\Windows\\Microsoft.NET\\Framework\\v2.0.50727",
 725         "C:\\Windows\\system32",
 726         "C:\\Windows",
 727         "C:\\Windows\\System32\\Wbem",
 728         "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\"
 729     ],
 730     "INCLUDE": [
 731         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Include",
 732         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Include\\Sys",
 733         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Include",
 734         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Include\\gl",
 735     ],
 736     "LIB": [
 737         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Lib\\x64",
 738         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Lib\\x64",
 739     ],
 740     "LIBPATH": [],
 741     "VSCMD_ARG_app_plat": [],
 742     "VCINSTALLDIR": [],
 743     "VCToolsInstallDir": []
 744 }
 745
 746 # Specifying MSVC_VERSION is recommended
 747 env = Environment(MSVC_VERSION='8.0', MSVC_USE_SETTINGS=msvc_use_settings)
 748 </programlisting>
 749 </para>
 750
 751 <para>
 752 Important usage details:
 753 <itemizedlist>
 754
 755 <listitem><para>
 756 &cv-MSVC_USE_SETTINGS; must be passed as an argument to the &f-link-Environment;
 757 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
 758 loaded via the default tools list or via a tools list passed to the
 759 &f-link-Environment; constructor.
 760 Otherwise, &cv-MSVC_USE_SETTINGS; must be set before the first msvc tool is
 761 loaded into the environment.
 762 </para></listitem>
 763
 764 <listitem><para>
 765 <emphasis>
 766 The dictionary content requirements are based on the internal msvc implementation and
 767 therefore may change at any time.
 768 </emphasis>
 769 The burden is on the user to ensure the dictionary contents are minimally sufficient to
 770 ensure successful builds.
 771 </para>
 772
 773 </listitem>
 774
 775 </itemizedlist>
 776 </para>
 777
 778 <para><emphasis>New in version 4.4</emphasis></para>
 779
 780 </summary>
 781 </cvar>
 782
 783 <!-- This has moved to Platform/Platform.xml to avoid duplication
 784 <cvar name="HOST_ARCH">
 785 <summary>
 786 <para>
 787 </para>
 788 </summary>
 789 </cvar>
 790 -->
 791
 792 <!-- This has moved to Platform/Platform.xml to avoid duplication
 793 <cvar name="TARGET_ARCH">
 794 <summary>
 795 <para>
 796 </para>
 797 </summary>
 798 </cvar>
 799 -->
 800
 801 <cvar name="MSVC_UWP_APP">
 802 <summary>
 803 <para>
 804 Build with the Universal Windows Platform (UWP) application &MSVC; libraries.
 805 </para>
 806
 807 <para>
 808 The valid values for &cv-MSVC_UWP_APP; are: <literal>True</literal>,
 809 <literal>'1'</literal>, <literal>False</literal>, <literal>'0'</literal>,
 810 or <literal>None</literal>.
 811 </para>
 812
 813 <para>
 814 When &cv-MSVC_UWP_APP; is enabled (i.e., <literal>True</literal> or
 815 <literal>'1'</literal>), the &MSVC; environment will be set up to point
 816 to the Windows Store compatible libraries and &MSVC; runtimes. In doing so,
 817 any libraries that are built will be able to be used in a UWP App and published
 818 to the Windows Store.
 819 <!-- This flag will only have an effect with Visual Studio 2015 or later. -->
 820 <!-- This variable must be passed as an argument to the Environment()
 821 constructor; setting it later has no effect. -->
 822 </para>
 823
 824 <para>
 825 An exception is raised when any of the following conditions are satisfied:
 826 <itemizedlist>
 827 <listitem><para>
 828 &cv-MSVC_UWP_APP; is enabled for Visual Studio 2013 and earlier.
 829 </para></listitem>
 830 <listitem><para>
 831 &cv-MSVC_UWP_APP; is enabled and a UWP argument is specified in
 832 &cv-link-MSVC_SCRIPT_ARGS;. Multiple UWP declarations via &cv-MSVC_UWP_APP;
 833 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
 834 </para></listitem>
 835 </itemizedlist>
 836 </para>
 837
 838 <para>
 839 Example - A Visual Studio 2022 build for the Universal Windows Platform:
 840 <example_commands>
 841 env = Environment(MSVC_VERSION='14.3', MSVC_UWP_APP=True)
 842 </example_commands>
 843 </para>
 844
 845 <para>
 846 Important usage details:
 847 <itemizedlist>
 848
 849 <listitem><para>
 850 &cv-MSVC_UWP_APP; must be passed as an argument to the &f-link-Environment;
 851 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
 852 loaded via the default tools list or via a tools list passed to the
 853 &f-link-Environment; constructor.
 854 Otherwise, &cv-MSVC_UWP_APP; must be set before the first msvc tool is
 855 loaded into the environment.
 856 </para></listitem>
 857
 858 <listitem><para>
 859 <emphasis>
 860 The existence of the UWP libraries is not verified when &cv-MSVC_UWP_APP; is enabled
 861 which could result in build failures.
 862 </emphasis>
 863 The burden is on the user to ensure the requisite UWP libraries are installed.
 864 </para></listitem>
 865
 866 </itemizedlist>
 867 </para>
 868
 869 </summary>
 870 </cvar>
 871
 872 <cvar name="VSWHERE">
 873 <summary>
 874 <para>
 875 Specify the location of <command>vswhere.exe</command>.
 876 </para>
 877
 878 <para>
 879     The <command>vswhere.exe</command> executable is distributed with
 880     Microsoft Visual Studio and Build Tools since the 2017 edition,
 881     but is also available as a standalone installation.
 882     It allows queries to obtain detailed information about
 883     installations of 2017 and later editions.
 884     &SCons; makes use of this information to determine
 885     the state of compiler support for those editions.
 886 </para>
 887 <para>
 888     Setting the &cv-VSWHERE; variable to the path to a specific
 889     <command>vswhere.exe</command> binary
 890     causes &SCons; to use that binary.
 891     If not set, &SCons; will search for one,
 892     looking in the following locations in order,
 893     using the first found
 894     (&cv-VSWHERE; is updated with the location):
 895 </para>
 896
 897 <simplelist type="vert">
 898 <member><literal>%ProgramFiles(x86)%\Microsoft Visual Studio\Installer</literal></member>
 899 <member><literal>%ProgramFiles%\Microsoft Visual Studio\Installer</literal></member>
 900 <member><literal>%ChocolateyInstall%\bin</literal></member>
 901 <member><literal>%LOCALAPPDATA%\Microsoft\WinGet\Links</literal></member>
 902 <member><literal>%USERPROFILE%\scoop\shims</literal></member>
 903 <member><literal>%SCOOP%\shims</literal></member>
 904 </simplelist>
 905
 906
 907 <note>
 908   <para>
 909     In order to take effect, &cv-VSWHERE; must be set before
 910     the initial &MSVC; compiler discovery takes place.
 911     Discovery happens, at the latest, during the first call to the
 912     &f-link-Environment; function, unless a <parameter>tools</parameter>
 913     list is specified which excludes the entire &MSVC; toolchain -
 914     that is, omits <literal>"defaults"</literal>
 915     and any specific tool module that refers to parts of the toolchain
 916     (&t-link-msvc;, &t-link-mslink;, &t-link-masm;, &t-link-midl;
 917     and &t-link-msvs;). In this case, detection is deferred until
 918     any one of those tool modules is invoked manually.
 919     The following two examples illustrate this:
 920   </para>
 921
 922   <programlisting>
 923 # VSWHERE set as Environment is created
 924 env = Environment(VSWHERE='c:/my/path/to/vswhere')
 925
 926 # Initialization deferred with empty tools, triggered manually
 927 env = Environment(tools=[])
 928 env['VSWHERE'] = r'c:/my/vswhere/install/location/vswhere.exe'
 929 env.Tool('msvc')
 930 env.Tool('mslink')
 931 env.Tool('msvs')
 932   </programlisting>
 933 </note>
 934
 935 </summary>
 936 </cvar>
 937
 938 <cvar name="MSVC_NOTFOUND_POLICY">
 939 <summary>
 940 <para>
 941 Specify the &scons; behavior when the &MSVC; compiler is not detected.
 942 </para>
 943
 944 <para>
 945     The &cv-MSVC_NOTFOUND_POLICY; specifies the &scons; behavior when no msvc versions are detected or
 946     when the requested msvc version is not detected.
 947 </para>
 948
 949 <para>
 950 The valid values for &cv-MSVC_NOTFOUND_POLICY; and the corresponding &scons; behavior are:
 951 </para>
 952
 953 <variablelist>
 954
 955 <varlistentry>
 956 <term><parameter>'Error' or 'Exception'</parameter></term>
 957 <listitem>
 958 <para>
 959 Raise an exception when no msvc versions are detected or when the requested msvc version is not detected.
 960 </para>
 961 </listitem>
 962 </varlistentry>
 963
 964 <varlistentry>
 965 <term><parameter>'Warning' or 'Warn'</parameter></term>
 966 <listitem>
 967 <para>
 968 Issue a warning and continue when no msvc versions are detected or when the requested msvc version is not detected.
 969 Depending on usage, this could result in build failure(s).
 970 </para>
 971 </listitem>
 972 </varlistentry>
 973
 974 <varlistentry>
 975 <term><parameter>'Ignore' or 'Suppress'</parameter></term>
 976 <listitem>
 977 <para>
 978 Take no action and continue when no msvc versions are detected or when the requested msvc version is not detected.
 979 Depending on usage, this could result in build failure(s).
 980 </para>
 981 </listitem>
 982 </varlistentry>
 983
 984 </variablelist>
 985
 986 <para>
 987 Note: in addition to the camel case values shown above, lower case and upper case values are accepted as well.
 988 </para>
 989
 990 <para>
 991 The &cv-MSVC_NOTFOUND_POLICY; is applied when any of the following conditions are satisfied:
 992 <itemizedlist>
 993 <listitem><para>
 994 &cv-MSVC_VERSION; is specified, the default tools list is implicitly defined (i.e., the tools list is not specified),
 995 and the default tools list contains one or more of the msvc tools.
 996 </para></listitem>
 997 <listitem><para>
 998 &cv-MSVC_VERSION; is specified, the default tools list is explicitly specified (e.g., <literal>tools=['default']</literal>),
 999 and the default tools list contains one or more of the msvc tools.
1000 </para></listitem>
1001 <listitem><para>
1002 A non-default tools list is specified that contains one or more of the msvc tools (e.g., <literal>tools=['msvc', 'mslink']</literal>).
1003 </para></listitem>
1004 </itemizedlist>
1005 </para>
1006
1007 <para>
1008 The &cv-MSVC_NOTFOUND_POLICY; is ignored when any of the following conditions are satisfied:
1009 <itemizedlist>
1010 <listitem><para>
1011 &cv-MSVC_VERSION; is not specified and the default tools list is implicitly defined (i.e., the tools list is not specified).
1012 </para></listitem>
1013 <listitem><para>
1014 &cv-MSVC_VERSION; is not specified and the default tools list is explicitly specified (e.g., <literal>tools=['default']</literal>).
1015 </para></listitem>
1016 <listitem><para>
1017 A non-default tool list is specified that does not contain any of the msvc tools (e.g., <literal>tools=['mingw']</literal>).
1018 </para></listitem>
1019 </itemizedlist>
1020 </para>
1021
1022 <para>
1023 Important usage details:
1024 <itemizedlist>
1025
1026 <listitem><para>
1027 &cv-MSVC_NOTFOUND_POLICY; must be passed as an argument to the &f-link-Environment;
1028 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
1029 loaded via the default tools list or via a tools list passed to the
1030 &f-link-Environment; constructor.
1031 Otherwise, &cv-MSVC_NOTFOUND_POLICY; must be set before the first msvc tool is
1032 loaded into the environment.
1033 </para></listitem>
1034
1035 </itemizedlist>
1036 </para>
1037
1038 <para>
1039 When &cv-MSVC_NOTFOUND_POLICY; is not specified, the default &scons; behavior is to issue a warning and continue
1040 subject to the conditions listed above. The default &scons; behavior may change in the future.
1041 </para>
1042
1043 <para><emphasis>New in version 4.4</emphasis></para>
1044
1045 </summary>
1046 </cvar>
1047
1048 <cvar name="MSVC_SCRIPTERROR_POLICY">
1049 <summary>
1050 <para>
1051 Specify the &scons; behavior when &MSVC; batch file errors are detected.
1052 </para>
1053
1054 <para>
1055 The &cv-MSVC_SCRIPTERROR_POLICY; specifies the &scons; behavior when msvc batch file errors are
1056 detected.
1057 When &cv-MSVC_SCRIPTERROR_POLICY; is not specified, the default &scons; behavior is to suppress
1058 msvc batch file error messages.
1059 </para>
1060 <para>
1061 The root cause of msvc build failures may be difficult to diagnose. In these situations, setting
1062 the &scons; behavior to issue a warning when msvc batch file errors are detected <emphasis>may</emphasis>
1063 produce additional diagnostic information.
1064 </para>
1065
1066 <para>
1067 The valid values for &cv-MSVC_SCRIPTERROR_POLICY; and the corresponding &scons; behavior are:
1068 </para>
1069
1070 <variablelist>
1071
1072 <varlistentry>
1073 <term><parameter>'Error' or 'Exception'</parameter></term>
1074 <listitem>
1075 <para>
1076 Raise an exception when msvc batch file errors are detected.
1077 </para>
1078 </listitem>
1079 </varlistentry>
1080
1081 <varlistentry>
1082 <term><parameter>'Warning' or 'Warn'</parameter></term>
1083 <listitem>
1084 <para>
1085 Issue a warning when msvc batch file errors are detected.
1086 </para>
1087 </listitem>
1088 </varlistentry>
1089
1090 <varlistentry>
1091 <term><parameter>'Ignore' or 'Suppress'</parameter></term>
1092 <listitem>
1093 <para>
1094 Suppress msvc batch file error messages.
1095 </para>
1096
1097 <para><emphasis>New in version 4.4</emphasis></para>
1098
1099 </listitem>
1100 </varlistentry>
1101
1102 </variablelist>
1103
1104 <para>
1105 Note: in addition to the camel case values shown above, lower case and upper case values are accepted as well.
1106 </para>
1107
1108 <para>
1109 Example 1 - A Visual Studio 2022 build with user-defined script arguments:
1110 <example_commands>
1111 env = environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['8.1', 'store', '-vcvars_ver=14.1'])
1112 env.Program('hello', ['hello.c'], CCFLAGS='/MD', LIBS=['kernel32', 'user32', 'runtimeobject'])
1113 </example_commands>
1114 </para>
1115
1116 <para>
1117 Example 1 - Output fragment:
1118 <example_commands>
1119 ...
1120 link /nologo /OUT:_build001\hello.exe kernel32.lib user32.lib runtimeobject.lib _build001\hello.obj
1121 LINK : fatal error LNK1104: cannot open file 'MSVCRT.lib'
1122 ...
1123 </example_commands>
1124 </para>
1125
1126 <para>
1127 Example 2 - A Visual Studio 2022 build with user-defined script arguments and the script error policy set
1128 to issue a warning when msvc batch file errors are detected:
1129 <example_commands>
1130 env = environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['8.1', 'store', '-vcvars_ver=14.1'], MSVC_SCRIPTERROR_POLICY='warn')
1131 env.Program('hello', ['hello.c'], CCFLAGS='/MD', LIBS=['kernel32', 'user32', 'runtimeobject'])
1132 </example_commands>
1133 </para>
1134
1135 <para>
1136 Example 2 - Output fragment:
1137 <example_commands>
1138 ...
1139 scons: warning: vc script errors detected:
1140 [ERROR:vcvars.bat] The UWP Application Platform requires a Windows 10 SDK.
1141 [ERROR:vcvars.bat] WindowsSdkDir = "C:\Program Files (x86)\Windows Kits\8.1\"
1142 [ERROR:vcvars.bat] host/target architecture is not supported : { x64 , x64 }
1143 ...
1144 link /nologo /OUT:_build001\hello.exe kernel32.lib user32.lib runtimeobject.lib _build001\hello.obj
1145 LINK : fatal error LNK1104: cannot open file 'MSVCRT.lib'
1146 </example_commands>
1147 </para>
1148
1149 <para>
1150 Important usage details:
1151 <itemizedlist>
1152
1153 <listitem><para>
1154 &cv-MSVC_SCRIPTERROR_POLICY; must be passed as an argument to the &f-link-Environment;
1155 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
1156 loaded via the default tools list or via a tools list passed to the
1157 &f-link-Environment; constructor.
1158 Otherwise, &cv-MSVC_SCRIPTERROR_POLICY; must be set before the first msvc tool is
1159 loaded into the environment.
1160 </para></listitem>
1161
1162 <listitem><para>
1163 Due to &scons; implementation details, not all Windows system environment variables are propagated
1164 to the environment in which the msvc batch file is executed.  Depending on Visual Studio version
1165 and installation options, non-fatal msvc batch file error messages may be generated for ancillary
1166 tools which may not affect builds with the msvc compiler.  For this reason, caution is recommended
1167 when setting the script error policy to raise an exception (e.g., <literal>'Error'</literal>).
1168 </para></listitem>
1169
1170 </itemizedlist>
1171 </para>
1172
1173 <para><emphasis>New in version 4.4</emphasis></para>
1174
1175 </summary>
1176 </cvar>
1177
1178 <cvar name="MSVC_SCRIPT_ARGS">
1179 <summary>
1180 <para>
1181 Pass user-defined arguments to the &MSVC; batch file determined via autodetection.
1182 </para>
1183
1184 <para>
1185 &cv-MSVC_SCRIPT_ARGS; is available for msvc batch file arguments that do not have first-class support
1186 via &consvars; or when there is an issue with the appropriate &consvar; validation.
1187 When available, it is recommended to use the appropriate &consvars; (e.g., &cv-link-MSVC_TOOLSET_VERSION;)
1188 rather than &cv-MSVC_SCRIPT_ARGS; arguments.
1189 </para>
1190
1191 <para>
1192 The valid values for &cv-MSVC_SCRIPT_ARGS; are: <literal>None</literal>, a string,
1193 or a list of strings.
1194 </para>
1195
1196 <para>
1197 The &cv-MSVC_SCRIPT_ARGS; value is converted to a scalar string (i.e., "flattened").
1198 The resulting scalar string, if not empty, is passed as an argument to the msvc batch file determined
1199 via autodetection subject to the validation conditions listed below.
1200 </para>
1201
1202 <para>
1203 &cv-MSVC_SCRIPT_ARGS; is ignored when the value is <literal>None</literal> and when the
1204 result from argument conversion is an empty string.  The validation conditions below do not apply.
1205 </para>
1206
1207 <para>
1208 An exception is raised when any of the following conditions are satisfied:
1209 <itemizedlist>
1210
1211 <listitem><para>
1212 &cv-MSVC_SCRIPT_ARGS; is specified for Visual Studio 2013 and earlier.
1213 </para></listitem>
1214
1215 <listitem><para>
1216 Multiple SDK version arguments (e.g., <literal>'10.0.20348.0'</literal>) are specified
1217 in &cv-MSVC_SCRIPT_ARGS;.
1218 </para></listitem>
1219
1220 <listitem><para>
1221 &cv-link-MSVC_SDK_VERSION; is specified and an SDK version argument
1222 (e.g., <literal>'10.0.20348.0'</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;.
1223 Multiple SDK version declarations via &cv-link-MSVC_SDK_VERSION; and &cv-MSVC_SCRIPT_ARGS;
1224 are not allowed.
1225 </para></listitem>
1226
1227 <listitem><para>
1228 Multiple toolset version arguments (e.g., <literal>'-vcvars_ver=14.29'</literal>)
1229 are specified in &cv-MSVC_SCRIPT_ARGS;.
1230 </para></listitem>
1231
1232 <listitem><para>
1233 &cv-link-MSVC_TOOLSET_VERSION; is specified and a toolset version argument
1234 (e.g., <literal>'-vcvars_ver=14.29'</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;.
1235 Multiple toolset version declarations via &cv-link-MSVC_TOOLSET_VERSION; and
1236 &cv-MSVC_SCRIPT_ARGS; are not allowed.
1237 </para></listitem>
1238
1239 <listitem><para>
1240 Multiple spectre library arguments (e.g., <literal>'-vcvars_spectre_libs=spectre'</literal>)
1241 are specified in &cv-MSVC_SCRIPT_ARGS;.
1242 </para></listitem>
1243
1244 <listitem><para>
1245 &cv-link-MSVC_SPECTRE_LIBS; is enabled and a spectre library argument
1246 (e.g., <literal>'-vcvars_spectre_libs=spectre'</literal>) is specified in
1247 &cv-MSVC_SCRIPT_ARGS;. Multiple spectre library declarations via &cv-link-MSVC_SPECTRE_LIBS;
1248 and &cv-MSVC_SCRIPT_ARGS; are not allowed.
1249 </para></listitem>
1250
1251 <listitem><para>
1252 Multiple UWP arguments (e.g., <literal>uwp</literal> or <literal>store</literal>) are specified
1253 in &cv-MSVC_SCRIPT_ARGS;.
1254 </para></listitem>
1255
1256 <listitem><para>
1257 &cv-link-MSVC_UWP_APP; is enabled and a UWP argument (e.g., <literal>uwp</literal> or
1258 <literal>store</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;. Multiple UWP declarations
1259 via &cv-link-MSVC_UWP_APP; and &cv-MSVC_SCRIPT_ARGS; are not allowed.
1260 </para></listitem>
1261
1262 </itemizedlist>
1263 </para>
1264
1265 <para>
1266 Example 1 - A Visual Studio 2022 build with an SDK version and a toolset version
1267 specified with a string argument:
1268 <example_commands>
1269 env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS='10.0.20348.0 -vcvars_ver=14.29.30133')
1270 </example_commands>
1271 </para>
1272
1273 <para>
1274 Example 2 - A Visual Studio 2022 build with an SDK version and a toolset version
1275 specified with a list argument:
1276 <example_commands>
1277 env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['10.0.20348.0', '-vcvars_ver=14.29.30133'])
1278 </example_commands>
1279 </para>
1280
1281 <para>
1282 Important usage details:
1283 <itemizedlist>
1284
1285 <listitem><para>
1286 &cv-MSVC_SCRIPT_ARGS; must be passed as an argument to the &f-link-Environment;
1287 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
1288 loaded via the default tools list or via a tools list passed to the
1289 &f-link-Environment; constructor.
1290 Otherwise, &cv-MSVC_SCRIPT_ARGS; must be set before the first msvc tool is
1291 loaded into the environment.
1292 </para></listitem>
1293
1294 <listitem><para>
1295 Other than checking for multiple declarations as described above, &cv-MSVC_SCRIPT_ARGS; arguments
1296 are not validated.
1297 </para></listitem>
1298
1299 <listitem><para>
1300 <emphasis>
1301 Erroneous, inconsistent, and/or version incompatible &cv-MSVC_SCRIPT_ARGS; arguments are likely
1302 to result in build failures for reasons that are not readily apparent and may be difficult to diagnose.
1303 </emphasis>
1304 The burden is on the user to ensure that the arguments provided to the msvc batch file are valid, consistent
1305 and compatible with the version of msvc selected.
1306 </para></listitem>
1307
1308 </itemizedlist>
1309 </para>
1310
1311 <para><emphasis>New in version 4.4</emphasis></para>
1312
1313 </summary>
1314 </cvar>
1315
1316 <cvar name="MSVC_SDK_VERSION">
1317 <summary>
1318 <para>
1319 Build with a specific version of the Microsoft Software Development Kit (SDK).
1320 </para>
1321
1322 <para>
1323 The valid values for &cv-MSVC_SDK_VERSION; are: <literal>None</literal>
1324 or a string containing the requested SDK version (e.g., <literal>'10.0.20348.0'</literal>).
1325 </para>
1326
1327 <para>
1328 &cv-MSVC_SDK_VERSION; is ignored when the value is <literal>None</literal> and when
1329 the value is an empty string.  The validation conditions below do not apply.
1330 </para>
1331
1332 <para>
1333 An exception is raised when any of the following conditions are satisfied:
1334 <itemizedlist>
1335
1336 <listitem><para>
1337 &cv-MSVC_SDK_VERSION; is specified for Visual Studio 2013 and earlier.
1338 </para></listitem>
1339
1340 <listitem><para>
1341 &cv-MSVC_SDK_VERSION; is specified and an SDK version argument is specified in
1342 &cv-link-MSVC_SCRIPT_ARGS;. Multiple SDK version declarations via &cv-MSVC_SDK_VERSION;
1343 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
1344 </para></listitem>
1345
1346 <listitem><para>
1347 The &cv-MSVC_SDK_VERSION; specified does not match any of the supported formats:
1348 <itemizedlist>
1349 <listitem><para>
1350 <literal>'10.0.XXXXX.Y'</literal> [SDK 10.0]
1351 </para></listitem>
1352 <listitem><para>
1353 <literal>'8.1'</literal> [SDK 8.1]
1354 </para></listitem>
1355 </itemizedlist>
1356 </para></listitem>
1357
1358 <listitem><para>
1359 The system folder for the corresponding &cv-MSVC_SDK_VERSION; version is not found.
1360 The requested SDK version does not appear to be installed.
1361 </para></listitem>
1362
1363 <listitem><para>
1364 The &cv-MSVC_SDK_VERSION; version does not appear to support the requested platform
1365 type (i.e., <literal>UWP</literal> or <literal>Desktop</literal>).  The requested SDK version
1366 platform type components do not appear to be installed.
1367 </para></listitem>
1368
1369 <listitem><para>
1370 The &cv-MSVC_SDK_VERSION; version is <literal>8.1</literal>, the platform type is
1371 <literal>UWP</literal>, and the build tools selected are from Visual Studio 2017
1372 and later (i.e., &cv-link-MSVC_VERSION; must be '14.0' or &cv-link-MSVC_TOOLSET_VERSION;
1373 must be '14.0').
1374 </para></listitem>
1375
1376 </itemizedlist>
1377 </para>
1378
1379 <para>
1380 Example 1 - A Visual Studio 2022 build with a specific Windows SDK version:
1381 <example_commands>
1382 env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.20348.0')
1383 </example_commands>
1384 </para>
1385
1386 <para>
1387 Example 2 - A Visual Studio 2022 build with a specific SDK version for the Universal Windows Platform:
1388 <example_commands>
1389 env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.20348.0', MSVC_UWP_APP=True)
1390 </example_commands>
1391 </para>
1392
1393 <para>
1394 Important usage details:
1395 <itemizedlist>
1396
1397 <listitem><para>
1398 &cv-MSVC_SDK_VERSION; must be passed as an argument to the &f-link-Environment;
1399 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
1400 loaded via the default tools list or via a tools list passed to the
1401 &f-link-Environment; constructor.
1402 Otherwise, &cv-MSVC_SDK_VERSION; must be set before the first msvc tool is
1403 loaded into the environment.
1404 </para></listitem>
1405
1406 <listitem>
1407 <para><emphasis>
1408 Should a SDK 10.0 version be installed that does not follow the naming scheme above, the
1409 SDK version will need to be specified via &cv-link-MSVC_SCRIPT_ARGS; until the version number
1410 validation format can be extended.
1411 </emphasis></para>
1412 </listitem>
1413
1414 <listitem><para>
1415 Should an exception be raised indicating that the SDK version is not found, verify that
1416 the requested SDK version is installed with the necessary platform type components.
1417 </para></listitem>
1418
1419 <listitem><para>
1420 There is a known issue with the Microsoft libraries when the target architecture is
1421 <literal>ARM64</literal> and a Windows 11 SDK (version <literal>'10.0.22000.0'</literal> and later) is used
1422 with the <literal>v141</literal> build tools and older <literal>v142</literal> toolsets
1423 (versions <literal>'14.28.29333'</literal> and earlier). Should build failures arise with these combinations
1424 of settings due to unresolved symbols in the Microsoft libraries, &cv-MSVC_SDK_VERSION; may be employed to
1425 specify a Windows 10 SDK (e.g., <literal>'10.0.20348.0'</literal>) for the build.
1426 </para></listitem>
1427
1428 </itemizedlist>
1429 </para>
1430
1431 <para><emphasis>New in version 4.4</emphasis></para>
1432
1433 </summary>
1434 </cvar>
1435
1436 <cvar name="MSVC_TOOLSET_VERSION">
1437 <summary>
1438 <para>
1439 Build with a specific &MSVC; toolset version.
1440 </para>
1441
1442 <para><emphasis>
1443 Specifying &cv-MSVC_TOOLSET_VERSION; does not affect the autodetection and selection
1444 of msvc instances. The &cv-MSVC_TOOLSET_VERSION; is applied <emphasis>after</emphasis>
1445 an msvc instance is selected. This could be the default version of msvc if &cv-link-MSVC_VERSION;
1446 is not specified.
1447 </emphasis></para>
1448
1449 <para>
1450 The valid values for &cv-MSVC_TOOLSET_VERSION; are: <literal>None</literal>
1451 or a string containing the requested toolset version (e.g., <literal>'14.29'</literal>).
1452 </para>
1453
1454 <para>
1455 &cv-MSVC_TOOLSET_VERSION; is ignored when the value is <literal>None</literal> and when
1456 the value is an empty string.  The validation conditions below do not apply.
1457 </para>
1458
1459 <para>
1460 An exception is raised when any of the following conditions are satisfied:
1461 <itemizedlist>
1462
1463 <listitem><para>
1464 &cv-MSVC_TOOLSET_VERSION; is specified for Visual Studio 2015 and earlier.
1465 </para></listitem>
1466
1467 <listitem><para>
1468 &cv-MSVC_TOOLSET_VERSION; is specified and a toolset version argument is specified in
1469 &cv-link-MSVC_SCRIPT_ARGS;. Multiple toolset version declarations via &cv-MSVC_TOOLSET_VERSION;
1470 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
1471 </para></listitem>
1472
1473 <listitem>
1474 <para>
1475 The &cv-MSVC_TOOLSET_VERSION; specified does not match any of the supported formats:
1476 </para>
1477
1478 <itemizedlist>
1479
1480 <listitem><para>
1481 <literal>'XX.Y'</literal>
1482 </para></listitem>
1483
1484 <listitem><para>
1485 <literal>'XX.YY'</literal>
1486 </para></listitem>
1487
1488 <listitem><para>
1489 <literal>'XX.YY.ZZZZZ'</literal>
1490 </para></listitem>
1491
1492 <listitem><para>
1493 <literal>'XX.YY.Z'</literal> to <literal>'XX.YY.ZZZZ'</literal>
1494 <emphasis>
1495 [&scons; extension not directly supported by the msvc batch files and may be removed in the future]
1496 </emphasis>
1497 </para></listitem>
1498
1499 <listitem><para>
1500 <literal>'XX.YY.ZZ.N'</literal> [SxS format]
1501 </para></listitem>
1502
1503 <listitem><para>
1504 <literal>'XX.YY.ZZ.NN'</literal> [SxS format]
1505 </para></listitem>
1506
1507 </itemizedlist>
1508
1509 </listitem>
1510
1511 <listitem><para>
1512 The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the &cv-MSVC_TOOLSET_VERSION; specified
1513 is for Visual Studio 2013 and earlier (e.g., <literal>'12.0'</literal>).
1514 </para></listitem>
1515
1516 <listitem><para>
1517 The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the &cv-MSVC_TOOLSET_VERSION; specified
1518 is greater than the msvc version selected (e.g., <literal>'99.0'</literal>).
1519 </para></listitem>
1520
1521 <listitem><para>
1522 A system folder for the corresponding &cv-MSVC_TOOLSET_VERSION; version is not found.
1523 The requested toolset version does not appear to be installed.
1524 </para></listitem>
1525
1526 </itemizedlist>
1527 </para>
1528
1529 <para>
1530 Toolset selection details:
1531 <itemizedlist>
1532
1533 <listitem><para>
1534 When &cv-MSVC_TOOLSET_VERSION; is not an SxS version number or a full toolset version number:
1535 the first toolset version, ranked in descending order, that matches the &cv-MSVC_TOOLSET_VERSION;
1536 prefix is selected.
1537 </para></listitem>
1538
1539 <listitem><para>
1540 When &cv-MSVC_TOOLSET_VERSION; is specified using the major msvc version prefix
1541 (i.e., <literal>'XX.Y'</literal>) and the major msvc version is that of the latest release of
1542 Visual Studio, the selected toolset version may not be the same as the default &MSVC; toolset version.
1543 </para><para>
1544 In the latest release of Visual Studio, the default &MSVC; toolset version is not necessarily the
1545 toolset with the largest version number.
1546 </para></listitem>
1547
1548 </itemizedlist>
1549 </para>
1550
1551 <para>
1552 Example 1 - A default Visual Studio build with a partial toolset version specified:
1553 <example_commands>
1554 env = Environment(MSVC_TOOLSET_VERSION='14.2')
1555 </example_commands>
1556 </para>
1557
1558 <para>
1559 Example 2 - A default Visual Studio build with a partial toolset version specified:
1560 <example_commands>
1561 env = Environment(MSVC_TOOLSET_VERSION='14.29')
1562 </example_commands>
1563 </para>
1564
1565 <para>
1566 Example 3 - A Visual Studio 2022 build with a full toolset version specified:
1567 <example_commands>
1568 env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.29.30133')
1569 </example_commands>
1570 </para>
1571
1572 <para>
1573 Example 4 - A Visual Studio 2022 build with an SxS toolset version specified:
1574 <example_commands>
1575 env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.29.16.11')
1576 </example_commands>
1577 </para>
1578
1579 <para>
1580 Important usage details:
1581 <itemizedlist>
1582
1583 <listitem><para>
1584 &cv-MSVC_TOOLSET_VERSION; must be passed as an argument to the &f-link-Environment;
1585 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
1586 loaded via the default tools list or via a tools list passed to the
1587 &f-link-Environment; constructor.
1588 Otherwise, &cv-MSVC_TOOLSET_VERSION; must be set before the first msvc tool is
1589 loaded into the environment.
1590 </para></listitem>
1591
1592 <listitem><para>
1593 <emphasis>
1594 The existence of the toolset host architecture and target architecture folders are not verified
1595 when &cv-MSVC_TOOLSET_VERSION; is specified which could result in build failures.
1596 </emphasis>
1597 The burden is on the user to ensure the requisite toolset target architecture build tools are installed.
1598 </para></listitem>
1599
1600 </itemizedlist>
1601 </para>
1602
1603 <para><emphasis>New in version 4.4</emphasis></para>
1604
1605 </summary>
1606 </cvar>
1607
1608 <cvar name="MSVC_SPECTRE_LIBS">
1609 <summary>
1610 <para>
1611 Build with the spectre-mitigated &MSVC; libraries.
1612 </para>
1613
1614 <para>
1615 The valid values for &cv-MSVC_SPECTRE_LIBS; are: <literal>True</literal>,
1616 <literal>False</literal>, or <literal>None</literal>.
1617 </para>
1618
1619 <para>
1620 When &cv-MSVC_SPECTRE_LIBS; is enabled (i.e., <literal>True</literal>),
1621 the &MSVC; environment will include the paths to the spectre-mitigated implementations
1622 of the &MSVC; libraries.
1623 </para>
1624
1625 <para>
1626 An exception is raised when any of the following conditions are satisfied:
1627 <itemizedlist>
1628
1629 <listitem><para>
1630 &cv-MSVC_SPECTRE_LIBS; is enabled for Visual Studio 2015 and earlier.
1631 </para></listitem>
1632
1633 <listitem><para>
1634 &cv-MSVC_SPECTRE_LIBS; is enabled and a spectre library argument is specified in
1635 &cv-link-MSVC_SCRIPT_ARGS;. Multiple spectre library declarations via &cv-MSVC_SPECTRE_LIBS;
1636 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
1637 </para></listitem>
1638
1639 <listitem><para>
1640 &cv-MSVC_SPECTRE_LIBS; is enabled and the platform type is <literal>UWP</literal>. There
1641 are no spectre-mitigated libraries for Universal Windows Platform (UWP) applications or
1642 components.
1643 </para></listitem>
1644
1645 </itemizedlist>
1646 </para>
1647
1648 <para>
1649 Example - A Visual Studio 2022 build with spectre mitigated &MSVC; libraries:
1650 <example_commands>
1651 env = Environment(MSVC_VERSION='14.3', MSVC_SPECTRE_LIBS=True)
1652 </example_commands>
1653 </para>
1654
1655 <para>
1656 Important usage details:
1657 <itemizedlist>
1658
1659 <listitem><para>
1660 &cv-MSVC_SPECTRE_LIBS; must be passed as an argument to the &f-link-Environment;
1661 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
1662 loaded via the default tools list or via a tools list passed to the
1663 &f-link-Environment; constructor.
1664 Otherwise, &cv-MSVC_SPECTRE_LIBS; must be set before the first msvc tool is
1665 loaded into the environment.
1666 </para></listitem>
1667
1668 <listitem><para>
1669 Additional compiler switches (e.g., <literal>/Qspectre</literal>) are necessary for including
1670 spectre mitigations when building user artifacts. Refer to the Visual Studio documentation for
1671 details.
1672 </para></listitem>
1673
1674 <listitem><para>
1675 <emphasis>
1676 The existence of the spectre libraries host architecture and target architecture folders are not
1677 verified when &cv-MSVC_SPECTRE_LIBS; is enabled which could result in build failures.
1678 </emphasis>
1679 The burden is on the user to ensure the requisite libraries with spectre mitigations are installed.
1680 </para></listitem>
1681
1682 </itemizedlist>
1683 </para>
1684
1685 <para><emphasis>New in version 4.4</emphasis></para>
1686
1687 </summary>
1688 </cvar>
1689
1690 </sconsdoc>