| blob | 88aa854978ac9ce3d724764b832e02ad842f7781 |
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
7 This file is processed by the bin/SConsDoc.py module.
8 -->
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 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:ns="http://www.scons.org/dbxsd/v1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" 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">
23 <tool name="msvs">
24 <summary>
25 <para>Sets &consvars; for Microsoft Visual Studio.</para>
26 </summary>
27 <sets>
28 <item>MSVSPROJECTCOM</item>
29 <item>MSVSSOLUTIONCOM</item>
30 <item>MSVSSCONSCRIPT</item>
31 <item>MSVSSCONS</item>
32 <item>MSVSSCONSFLAGS</item>
33 <item>MSVSSCONSCOM</item>
34 <item>MSVSBUILDCOM</item>
35 <item>MSVSREBUILDCOM</item>
36 <item>MSVSCLEANCOM</item>
37 <item>MSVSENCODING</item>
38 </sets>
39 <uses />
40 </tool>
41 <builder name="MSVSProject">
42 <summary>
43 <para>
44 Build a &MSVC; project file and solution file.
45 </para>
46 <para>
47 Builds a &MSVC; project file based on the
48 version of Visual Studio (or to be more precise, of
49 <application>MSBuild</application>)
50 that is configured: either the latest installed version,
51 or the version specified by
52 &cv-link-MSVC_VERSION; in the current &consenv;.
53 For Visual Studio 6.0 a <filename>.dsp</filename> file is generated.
54 For Visual Studio versions 2002-2008,
55 a <filename>.vcproj</filename> file is generated.
56 For Visual Studio 2010 and later a <filename>.vcxproj</filename>
57 file is generated.
58 Note there are multiple versioning schemes involved in
59 the Microsoft compilation environment -
60 see the description of &cv-link-MSVC_VERSION; for equivalences.
61 Note &SCons; does not know how to construct project files for
62 other languages (e.g. <filename>.csproj</filename> for C#,
63 <filename>.vbproj</filename> for Visual Basic or
64 <filename>.pyproject</filename> for Python).
65 </para>
66 <para>
67 For the <filename>.vcxproj</filename> file, the underlying
68 format is the MSBuild XML Schema, and the details conform to:
69 <ulink url="https://learn.microsoft.com/en-us/cpp/build/reference/vcxproj-file-structure">
70 https://learn.microsoft.com/en-us/cpp/build/reference/vcxproj-file-structure</ulink>.
71 The generated solution file enables Visual Studio to
72 understand the project structure, and allows building it
73 using <application>MSBuild</application> to call back to &SCons;.
74 The project file encodes a toolset version that has been
75 selected by &SCons; as described above. Since recent Visual
76 Studio versions support multiple concurrent toolsets,
77 use &cv-link-MSVC_VERSION; to select the desired one if
78 it does not match the &SCons; default.
79 The project file also includes entries which describe
80 how to call &SCons; to build the project from within Visual Studio
81 (or from an <application>MSBuild</application> command line).
82 In some situations &SCons; may generate this incorrectly -
83 notably when using the <emphasis>scons-local</emphasis>
84 distribution, which is not installed in a way that that
85 matches the default invocation line.
86 If so, the &cv-link-SCONS_HOME; &consvar; can be used to describe
87 the right way to locate the &SCons; code so that it can be imported.
88 </para>
89 <para>
90 By default, a matching solution file for the project is also generated.
91 This behavior may be disabled by
92 specifying <parameter>auto_build_solution=0</parameter>
93 to the &b-MSVSProject; builder.
94 The solution file can also be independently
95 generated by calling the &b-MSVSSolution; builder,
96 such as in the case where a solution should describe
97 multiple projects.
98 See the &b-link-MSVSSolution; description for further information.
99 </para>
100 <para>
101 The &b-MSVSProject; builder accepts several keyword arguments
102 describing lists of filenames to be placed into the project file.
103 Currently,
104 <parameter>srcs</parameter>,
105 <parameter>incs</parameter>,
106 <parameter>localincs</parameter>,
107 <parameter>resources</parameter>,
108 and <parameter>misc</parameter>
109 are recognized.
110 The names are intended to be self-explanatory, but note that the
111 filenames need to be specified as strings, <emphasis>not</emphasis>
112 as &SCons; File Nodes
113 (for example if you generate files for inclusion by using the
114 &f-link-Glob; function, the results should be converted to
115 a list of strings before passing them to &b-MSVSProject;).
116 This is because Visual Studio and
117 <application>MSBuild</application> know nothing about &SCons;
118 Node types.
119 Each of the filename lists are individually optional, but at
120 least one list must be specified for the resulting project file to
121 be non-empty.
122 </para>
123 <para>
124 In addition to the above lists of values, the following values
125 may be specified as keyword arguments:
126 </para>
127 <variablelist>
128 <varlistentry>
129 <term><parameter>target</parameter></term>
130 <listitem>
131 <para>
132 The name of the target <filename>.dsp</filename>
133 or <filename>.vcproj</filename> file.
134 The correct suffix for the version of Visual Studio
135 must be used, but the &cv-link-MSVSPROJECTSUFFIX;
136 &consvar; will be defined to the correct
137 value (see example below).
138 </para>
139 </listitem>
140 </varlistentry>
141 <varlistentry>
142 <term><parameter>variant</parameter></term>
143 <listitem>
144 <para>
145 The name of this particular variant. Except for Visual Studio 6
146 projects, this can also be a list of variant names. These
147 are typically things like "Debug" or "Release", but
148 really can be anything you want. For Visual Studio
149 7 projects, they may also specify a target platform
150 separated from the variant name by a <literal>|</literal>
151 (vertical pipe) character: <literal>Debug|Xbox</literal>.
152 The default target platform is Win32. Multiple calls
153 to &b-MSVSProject; with different variants are allowed;
154 all variants will be added to the project file with
155 their appropriate build targets and sources.
156 </para>
157 </listitem>
158 </varlistentry>
159 <varlistentry>
160 <term><parameter>cmdargs</parameter></term>
161 <listitem>
162 <para>
163 Additional command line arguments
164 for the different variants. The number of
165 <parameter>cmdargs</parameter> entries must match the number
166 of <parameter>variant</parameter> entries, or be empty (not
167 specified). If you give only one, it will automatically
168 be propagated to all variants.
169 </para>
170 </listitem>
171 </varlistentry>
172 <varlistentry>
173 <term><parameter>cppdefines</parameter></term>
174 <listitem>
175 <para>
176 Preprocessor definitions for the different variants.
177 The number of <parameter>cppdefines</parameter> entries
178 must match the number of <parameter>variant</parameter>
179 entries, or be empty (not specified). If you give
180 only one, it will automatically be propagated to all
181 variants. If you don't give this parameter, &SCons;
182 will use the invoking environment's
183 &cv-link-CPPDEFINES; entry for all variants.
184 </para>
185 </listitem>
186 </varlistentry>
187 <varlistentry>
188 <term><parameter>cppflags</parameter></term>
189 <listitem>
190 <para>
191 Compiler flags for the different variants.
192 If a <option>/std:c++</option> flag is found then
193 <option>/Zc:__cplusplus</option> is appended to the
194 flags if not already found, this ensures that Intellisense
195 uses the <option>/std:c++</option> switch.
196 The number of <parameter>cppflags</parameter> entries
197 must match the number of <parameter>variant</parameter>
198 entries, or be empty (not specified). If you give
199 only one, it will automatically be propagated to all
200 variants. If you don't give this parameter, SCons
201 will combine the invoking environment's
202 &cv-link-CCFLAGS;, &cv-link-CXXFLAGS;,
203 &cv-link-CPPFLAGS; entries for all variants.
204 </para>
205 </listitem>
206 </varlistentry>
207 <varlistentry>
208 <term><parameter>cpppaths</parameter></term>
209 <listitem>
210 <para>
211 Compiler include paths for the different variants.
212 The number of <parameter>cpppaths</parameter> entries
213 must match the number of <parameter>variant</parameter>
214 entries, or be empty (not specified). If you give
215 only one, it will automatically be propagated to all
216 variants. If you don't give this parameter, SCons
217 will use the invoking environment's
218 &cv-link-CPPPATH; entry for all variants.
219 </para>
220 </listitem>
221 </varlistentry>
222 <varlistentry>
223 <term><parameter>buildtarget</parameter></term>
224 <listitem>
225 <para>
226 An optional string, node, or list of strings
227 or nodes (one per build variant), to tell
228 the Visual Studio debugger what output target
229 to use in what build variant. The number of
230 <parameter>buildtarget</parameter> entries must match the
231 number of <parameter>variant</parameter> entries.
232 </para>
233 </listitem>
234 </varlistentry>
235 <varlistentry>
236 <term><parameter>runfile</parameter></term>
237 <listitem>
238 <para>
239 The name of the file that Visual Studio 7 and
240 later will run and debug. This appears as the
241 value of the <parameter>Output</parameter> field in the
242 resulting &MSVC; project file. If this is not
243 specified, the default is the same as the specified
244 <parameter>buildtarget</parameter> value.
245 </para>
246 </listitem>
247 </varlistentry>
248 </variablelist>
249 <note>
250 <para>
251 &SCons; and Microsoft Visual Studio understand projects in
252 different ways, and the mapping is sometimes imperfect:
253 </para>
254 <para>
255 Because &SCons; always executes its build commands
256 from the directory in which the &SConstruct; file is located,
257 if you generate a project file in a different directory
258 than the directory of the &SConstruct; file, users will not be able to
259 double-click on the file name in compilation error messages
260 displayed in the Visual Studio console output window. This can
261 be remedied by adding the &MSVC; <option>/FC</option>
262 compiler option to the &cv-link-CCFLAGS; variable so that
263 the compiler will print the full path name of any files that
264 cause compilation errors.
265 </para>
266 <para>
267 If the project file is only used to teach the Visual Studio
268 project browser about the file layout there should be no issues,
269 However, Visual Studio should not be used to make changes
270 to the project structure, build options, etc. as these will
271 (a) not feed back to the &SCons; description of the project
272 and (b) be lost if &SCons; regenerates the project file.
273 The SConscript files should remain the definitive description
274 of the build.
275 </para>
276 <para>
277 If the project file is used to drive
278 <application>MSBuild</application> (such as selecting
279 "build" from the Visual Studio interface) you lose the direct
280 control of target selection and command-line options you would
281 have if launching the build directly from &SCons;,
282 because these will be hard-coded in the project file to the
283 values specified in the &b-MSVSProject; call.
284 You can regain some of this control by defining multiple variants,
285 using multiple &b-MSVSProject; calls to arrange different build
286 targets, arguments, defines, flags and paths for different variants.
287 </para>
288 <para>
289 If the build is divided into a solution with multiple
290 <application>MSBuild</application>
291 projects the mapping is further strained. In this case,
292 it is important not to set Visual Studio to do parallel builds,
293 as it will then launch the separate project builds in parallel,
294 and &SCons; does not work well if called that way.
295 Instead, you can set up the &SCons; build for parallel building -
296 see the &f-link-SetOption; function for how to do this with
297 <parameter>num_jobs</parameter>.
298 </para>
299 </note>
301 <para>Example usage:</para>
302 <example_commands>
303 barsrcs = ['bar.cpp']
304 barincs = ['bar.h']
305 barlocalincs = ['StdAfx.h']
306 barresources = ['bar.rc', 'resource.h']
307 barmisc = ['bar_readme.txt']
309 dll = env.SharedLibrary(target='bar.dll', source=barsrcs)
310 buildtarget = [s for s in dll if str(s).endswith('dll')]
311 env.MSVSProject(
312 target='Bar' + env['MSVSPROJECTSUFFIX'],
313 srcs=barsrcs,
314 incs=barincs,
315 localincs=barlocalincs,
316 resources=barresources,
317 misc=barmisc,
318 buildtarget=buildtarget,
319 variant='Release',
320 )
321 </example_commands>
323 <variablelist>
324 <varlistentry>
325 <term><parameter>DebugSettings</parameter></term>
326 <listitem>
327 <para>
328 A dictionary of debug settings that get written
329 to the <filename>.vcproj.user</filename> or the
330 <filename>.vcxproj.user</filename> file, depending on the
331 version installed. As for <parameter>cmdargs</parameter>,
332 you can specify a <parameter>DebugSettings</parameter>
333 dictionary per variant. If you give only one, it will
334 be propagated to all variants.
335 </para>
336 <para>
337 <emphasis>Changed in version 2.4:</emphasis>
338 Added the optional <parameter>DebugSettings</parameter> parameter.
339 </para>
340 </listitem>
341 </varlistentry>
342 </variablelist>
343 <para>
344 Currently, only Visual Studio v9.0 and Visual Studio
345 version v11 are implemented, for other versions no file
346 is generated. To generate the user file, you just need to
347 add a <parameter>DebugSettings</parameter> dictionary to the
348 environment with the right parameters for your MSVS version. If
349 the dictionary is empty, or does not contain any good value,
350 no file will be generated.
351 </para>
352 <para>
353 Following is a more contrived example, involving the setup
354 of a project for variants and DebugSettings:
355 </para>
356 <example_commands>
357 # Assuming you store your defaults in a file
358 vars = Variables('variables.py')
359 msvcver = vars.args.get('vc', '9')
361 # Check command args to force one Microsoft Visual Studio version
362 if msvcver == '9' or msvcver == '11':
363 env = Environment(MSVC_VERSION=msvcver + '.0', MSVC_BATCH=False)
364 else:
365 env = Environment()
367 AddOption(
368 '--userfile',
369 action='store_true',
370 dest='userfile',
371 default=False,
372 help="Create Visual C++ project file",
373 )
375 #
376 # 1. Configure your Debug Setting dictionary with options you want in the list
377 # of allowed options, for instance if you want to create a user file to launch
378 # a specific application for testing your dll with Microsoft Visual Studio 2008 (v9):
379 #
380 V9DebugSettings = {
381 'Command': 'c:\\myapp\\using\\thisdll.exe',
382 'WorkingDirectory': 'c:\\myapp\\using\\',
383 'CommandArguments': '-p password',
384 # 'Attach':'false',
385 # 'DebuggerType':'3',
386 # 'Remote':'1',
387 # 'RemoteMachine': None,
388 # 'RemoteCommand': None,
389 # 'HttpUrl': None,
390 # 'PDBPath': None,
391 # 'SQLDebugging': None,
392 # 'Environment': '',
393 # 'EnvironmentMerge':'true',
394 # 'DebuggerFlavor': None,
395 # 'MPIRunCommand': None,
396 # 'MPIRunArguments': None,
397 # 'MPIRunWorkingDirectory': None,
398 # 'ApplicationCommand': None,
399 # 'ApplicationArguments': None,
400 # 'ShimCommand': None,
401 # 'MPIAcceptMode': None,
402 # 'MPIAcceptFilter': None,
403 }
405 #
406 # 2. Because there are a lot of different options depending on the Microsoft
407 # Visual Studio version, if you use more than one version you have to
408 # define a dictionary per version, for instance if you want to create a user
409 # file to launch a specific application for testing your dll with Microsoft
410 # Visual Studio 2012 (v11):
411 #
412 V10DebugSettings = {
413 'LocalDebuggerCommand': 'c:\\myapp\\using\\thisdll.exe',
414 'LocalDebuggerWorkingDirectory': 'c:\\myapp\\using\\',
415 'LocalDebuggerCommandArguments': '-p password',
416 # 'LocalDebuggerEnvironment': None,
417 # 'DebuggerFlavor': 'WindowsLocalDebugger',
418 # 'LocalDebuggerAttach': None,
419 # 'LocalDebuggerDebuggerType': None,
420 # 'LocalDebuggerMergeEnvironment': None,
421 # 'LocalDebuggerSQLDebugging': None,
422 # 'RemoteDebuggerCommand': None,
423 # 'RemoteDebuggerCommandArguments': None,
424 # 'RemoteDebuggerWorkingDirectory': None,
425 # 'RemoteDebuggerServerName': None,
426 # 'RemoteDebuggerConnection': None,
427 # 'RemoteDebuggerDebuggerType': None,
428 # 'RemoteDebuggerAttach': None,
429 # 'RemoteDebuggerSQLDebugging': None,
430 # 'DeploymentDirectory': None,
431 # 'AdditionalFiles': None,
432 # 'RemoteDebuggerDeployDebugCppRuntime': None,
433 # 'WebBrowserDebuggerHttpUrl': None,
434 # 'WebBrowserDebuggerDebuggerType': None,
435 # 'WebServiceDebuggerHttpUrl': None,
436 # 'WebServiceDebuggerDebuggerType': None,
437 # 'WebServiceDebuggerSQLDebugging': None,
438 }
440 #
441 # 3. Select the dictionary you want depending on the version of Visual Studio
442 # Files you want to generate.
443 #
444 if not env.GetOption('userfile'):
445 dbgSettings = None
446 elif env.get('MSVC_VERSION', None) == '9.0':
447 dbgSettings = V9DebugSettings
448 elif env.get('MSVC_VERSION', None) == '11.0':
449 dbgSettings = V10DebugSettings
450 else:
451 dbgSettings = None
453 #
454 # 4. Add the dictionary to the DebugSettings keyword.
455 #
456 barsrcs = ['bar.cpp', 'dllmain.cpp', 'stdafx.cpp']
457 barincs = ['targetver.h']
458 barlocalincs = ['StdAfx.h']
459 barresources = ['bar.rc', 'resource.h']
460 barmisc = ['ReadMe.txt']
462 dll = env.SharedLibrary(target='bar.dll', source=barsrcs)
464 env.MSVSProject(
465 target='Bar' + env['MSVSPROJECTSUFFIX'],
466 srcs=barsrcs,
467 incs=barincs,
468 localincs=barlocalincs,
469 resources=barresources,
470 misc=barmisc,
471 buildtarget=[dll[0]] * 2,
472 variant=('Debug|Win32', 'Release|Win32'),
473 cmdargs=f'vc={msvcver}',
474 DebugSettings=(dbgSettings, {}),
475 )
476 </example_commands>
477 </summary>
478 </builder>
479 <builder name="MSVSSolution">
480 <summary>
481 <para>Build a Microsoft Visual Studio Solution file.</para>
482 <para>
483 Builds a Visual Studio solution file based on the
484 version of Visual Studio that is configured: either the
485 latest installed version, or the version specified by
486 &cv-link-MSVC_VERSION; in the &consenv;. For
487 Visual Studio 6, a <filename>.dsw</filename> file is generated.
488 For Visual Studio .NET 2002 and later,
489 it will generate a <filename>.sln</filename> file.
490 Note there are multiple versioning schemes involved in
491 the Microsoft compilation environment -
492 see the description of &cv-link-MSVC_VERSION; for equivalences.
493 </para>
494 <para>
495 The solution file is a container for one or more projects,
496 and follows the format described at
497 <ulink url="https://learn.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file">
498 https://learn.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file</ulink>.
499 </para>
500 <para>The following values must be specified:</para>
501 <variablelist>
502 <varlistentry>
503 <term><parameter>target</parameter></term>
504 <listitem>
505 <para>
506 The name of the target <filename>.dsw</filename> or
507 <filename>.sln</filename> file. The correct
508 suffix for the version of Visual Studio must be used,
509 but the value &cv-link-MSVSSOLUTIONSUFFIX; will be
510 defined to the correct value (see example below).
511 </para>
512 </listitem>
513 </varlistentry>
514 <varlistentry>
515 <term><parameter>variant</parameter></term>
516 <listitem>
517 <para>
518 The name of this particular variant, or a list of
519 variant names (the latter is only supported for MSVS
520 7 solutions). These are typically things like "Debug"
521 or "Release", but really can be anything you want. For
522 MSVS 7 they may also specify target platform, like this
523 <literal>"Debug|Xbox"</literal>. Default platform is Win32.
524 </para>
525 </listitem>
526 </varlistentry>
527 <varlistentry>
528 <term><parameter>projects</parameter></term>
529 <listitem>
530 <para>
531 A list of project file names, or Project nodes returned
532 by calls to the &b-link-MSVSProject; Builder, to be placed
533 into the solution file.
534 Note that these filenames need to be specified as strings,
535 NOT as &SCons; File Nodes.
536 This is because the solution file will be interpreted by
537 <application>MSBuild</application>
538 and by Visual Studio, which know nothing about &SCons; Node types.
539 </para>
540 </listitem>
541 </varlistentry>
542 </variablelist>
543 <para>
544 In addition to the mandatory arguments above, the following optional
545 values may be specified as keyword arguments:
546 </para>
547 <variablelist>
548 <varlistentry>
549 <term><parameter>auto_filter_projects</parameter></term>
550 <listitem>
551 <para>
552 Under certain circumstances, solution file names or
553 solution file nodes may be present in the
554 <parameter>projects</parameter> argument list.
555 When solution file names or nodes are present in the
556 <parameter>projects</parameter> argument list, the generated
557 solution file may contain erroneous Project records resulting
558 in VS IDE error messages when opening the generated solution
559 file.
560 By default, an exception is raised when a solution file
561 name or solution file node is detected in the
562 <parameter>projects</parameter> argument list.
563 </para>
564 <para>
565 The accepted values for <parameter>auto_filter_projects</parameter>
566 are:
567 </para>
568 <variablelist>
569 <varlistentry>
570 <term><parameter>None</parameter></term>
571 <listitem>
572 <para>
573 An exception is raised when a solution file name or solution
574 file node is detected in the <parameter>projects</parameter>
575 argument list.
576 </para>
577 <para>
578 <parameter>None</parameter> is the default value.
579 </para>
580 </listitem>
581 </varlistentry>
582 <varlistentry>
583 <term><parameter>True or evaluates True</parameter></term>
584 <listitem>
585 <para>
586 Automatically remove solution file names and solution file
587 nodes from the <parameter>projects</parameter> argument list.
588 </para>
589 </listitem>
590 </varlistentry>
591 <varlistentry>
592 <term><parameter>False or evaluates False</parameter></term>
593 <listitem>
594 <para>
595 Leave the solution file names and solution file nodes
596 in the <parameter>projects</parameter> argument list.
597 An exception is not raised.
598 </para>
599 <para>
600 When opening the generated solution file with the VS IDE,
601 the VS IDE will likely report that there are erroneous
602 Project records that are not supported or that need to be
603 modified.
604 </para>
605 </listitem>
606 </varlistentry>
607 </variablelist>
608 </listitem>
609 </varlistentry>
610 </variablelist>
611 <para>Example Usage:</para>
612 <example_commands>
613 env.MSVSSolution(
614 target="Bar" + env["MSVSSOLUTIONSUFFIX"],
615 projects=["bar" + env["MSVSPROJECTSUFFIX"]],
616 variant="Release",
617 )
618 </example_commands>
619 </summary>
620 </builder> <cvar name="MSVS">
621 <summary>
622 <para>
623 When the Microsoft Visual Studio tools are initialized,
624 they set up this dictionary with the following keys:
625 </para>
626 <variablelist>
627 <varlistentry>
628 <term>VERSION</term>
629 <listitem>
630 <para>the version of MSVS being used (can be set via
631 &cv-link-MSVC_VERSION;)</para>
632 </listitem>
633 </varlistentry>
634 <varlistentry>
635 <term>VERSIONS</term>
636 <listitem>
637 <para>the available versions of MSVS installed</para>
638 </listitem>
639 </varlistentry>
640 <varlistentry>
641 <term>VCINSTALLDIR</term>
642 <listitem>
643 <para>installed directory of &MSVC;</para>
644 </listitem>
645 </varlistentry>
646 <varlistentry>
647 <term>VSINSTALLDIR</term>
648 <listitem>
649 <para>installed directory of Visual Studio</para>
650 </listitem>
651 </varlistentry>
652 <varlistentry>
653 <term>FRAMEWORKDIR</term>
654 <listitem>
655 <para>installed directory of the .NET framework</para>
656 </listitem>
657 </varlistentry>
658 <varlistentry>
659 <term>FRAMEWORKVERSIONS</term>
660 <listitem>
661 <para>
662 list of installed versions of the .NET framework,
663 sorted latest to oldest.
664 </para>
665 </listitem>
666 </varlistentry>
667 <varlistentry>
668 <term>FRAMEWORKVERSION</term>
669 <listitem>
670 <para>latest installed version of the .NET framework</para>
671 </listitem>
672 </varlistentry>
673 <varlistentry>
674 <term>FRAMEWORKSDKDIR</term>
675 <listitem>
676 <para>installed location of the .NET SDK.</para>
677 </listitem>
678 </varlistentry>
679 <varlistentry>
680 <term>PLATFORMSDKDIR</term>
681 <listitem>
682 <para>installed location of the Platform SDK.</para>
683 </listitem>
684 </varlistentry>
685 <varlistentry>
686 <term>PLATFORMSDK_MODULES</term>
687 <listitem>
688 <para>
689 dictionary of installed Platform SDK modules, where the
690 dictionary keys are keywords for the various modules,
691 and the values are 2-tuples where the first is the
692 release date, and the second is the version number.
693 </para>
694 </listitem>
695 </varlistentry>
696 </variablelist>
697 <para>If a value is not set, it was not available in the registry.
698 Visual Studio 2017 and later do not use the registry for
699 primary storage of this information, so typically for these
700 versions only <literal>PROJECTSUFFIX</literal> and
701 <literal>SOLUTIONSUFFIX</literal> will be set.
702 </para>
703 </summary>
704 </cvar> <cvar name="MSVS_ARCH">
705 <summary>
706 <para>Sets the architecture for which the generated project(s) should build.</para>
707 <para>
708 The default value is <literal>x86</literal>.
709 <literal>amd64</literal> is also supported by &SCons; for
710 most Visual Studio versions. Since Visual Studio 2015
711 <literal>arm</literal> is supported, and since Visual Studio
712 2017 <literal>arm64</literal> is supported.
713 Trying to set &cv-MSVS_ARCH;
714 to an architecture that's not supported for a given Visual
715 Studio version will generate an error.
716 </para>
717 </summary>
718 </cvar> <cvar name="MSVS_PROJECT_GUID">
719 <summary>
720 <para>
721 The string placed in a generated
722 &MSVC; project file as the value of the
723 <literal>ProjectGUID</literal> attribute. There is no default
724 value. If not defined, a new GUID is generated.
725 </para>
726 </summary>
727 </cvar> <cvar name="MSVS_SCC_AUX_PATH">
728 <summary>
729 <para>
730 The path name placed in a generated
731 &MSVC; project file as the value of the
732 <literal>SccAuxPath</literal> attribute if the
733 <envar>MSVS_SCC_PROVIDER</envar> &consvar; is
734 also set. There is no default value.
735 </para>
736 </summary>
737 </cvar> <cvar name="MSVS_SCC_CONNECTION_ROOT">
738 <summary>
739 <para>
740 The root path of projects in your SCC workspace, i.e the
741 path under which all project and solution files will be
742 generated. It is used as a reference path from which the
743 relative paths of the generated &MSVC; project
744 and solution files are computed. The relative project file path
745 is placed as the value of the <literal>SccLocalPath</literal>
746 attribute of the project file and as the values of the
747 <literal>SccProjectFilePathRelativizedFromConnection[i]</literal>
748 (where [i] ranges from 0 to the number of projects in the solution)
749 attributes of the <literal>GlobalSection(SourceCodeControl)</literal>
750 section of the Microsoft Visual Studio solution file. Similarly,
751 the relative solution file path is placed as the values of the
752 <literal>SccLocalPath[i]</literal> (where [i] ranges from 0
753 to the number of projects in the solution) attributes of the
754 <literal>GlobalSection(SourceCodeControl)</literal> section of
755 the Microsoft Visual Studio solution file. This is used only if
756 the <envar>MSVS_SCC_PROVIDER</envar> &consvar; is
757 also set. The default value is the current working directory.
758 </para>
759 </summary>
760 </cvar> <cvar name="MSVS_SCC_PROJECT_NAME">
761 <summary>
762 <para>
763 The project name placed in a generated &MSVC;
764 project file as the value of the
765 <literal>SccProjectName</literal> attribute if the
766 <envar>MSVS_SCC_PROVIDER</envar> &consvar;
767 is also set. In this case the string is also placed in
768 the <literal>SccProjectName0</literal> attribute of the
769 <literal>GlobalSection(SourceCodeControl)</literal> section
770 of the Microsoft Visual Studio solution file. There is no
771 default value.
772 </para>
773 </summary>
774 </cvar> <cvar name="MSVS_SCC_PROVIDER">
775 <summary>
776 <para>
777 The string placed in a generated &MSVC;
778 project file as the value of the
779 <literal>SccProvider</literal> attribute. The string is
780 also placed in the <literal>SccProvider0</literal> attribute
781 of the <literal>GlobalSection(SourceCodeControl)</literal>
782 section of the Microsoft Visual Studio solution file. There
783 is no default value.
784 </para>
785 </summary>
786 </cvar> <cvar name="MSVS_VERSION">
787 <summary>
788 <para>Set the preferred version of Microsoft Visual Studio to use.</para>
789 <para>
790 If &cv-MSVS_VERSION; is not set, &SCons; will (by default)
791 select the latest version of Visual Studio installed on your
792 system. So, if you have version 6 and version 7 (MSVS .NET)
793 installed, it will prefer version 7. You can override this by
794 specifying the &cv-link-MSVS_VERSION; variable when
795 initializing the Environment, setting it to the appropriate
796 version ('6.0' or '7.0', for example). If the specified
797 version isn't installed, tool initialization will fail.
798 </para>
799 <para>
800 <emphasis>Deprecated since 1.3.0:</emphasis>
801 &cv-MSVS_VERSION; is deprecated in favor of &cv-link-MSVC_VERSION;.
802 As a transitional aid, if &cv-MSVS_VERSION; is set
803 and &cv-MSVC_VERSION; is not,
804 &cv-MSVC_VERSION; will be initialized to the value
805 of &cv-MSVS_VERSION;.
806 An error is raised if both are set and have different values.
807 </para>
808 </summary>
809 </cvar>
810 <cvar name="MSVSBUILDCOM">
811 <summary>
812 <para>
813 The build command line placed in a generated &MSVC;
814 project file. The default is to have Visual Studio
815 invoke &SCons; with any specified build targets.
816 </para>
817 </summary>
818 </cvar>
819 <cvar name="MSVSCLEANCOM">
820 <summary>
821 <para>
822 The clean command line placed in a generated &MSVC;
823 project file. The default is to have Visual Studio
824 invoke &SCons; with the <option>-c</option> option to remove
825 any specified targets.
826 </para>
827 </summary>
828 </cvar> <cvar name="MSVSENCODING">
829 <summary>
830 <para>
831 The encoding string placed in a generated &MSVC;
832 project file. The default is encoding
833 <literal>Windows-1252</literal>.
834 </para>
835 </summary>
836 </cvar>
837 <cvar name="MSVSPROJECTCOM">
838 <summary>
839 <para>The action used to generate &MSVC; project files.</para>
840 </summary>
841 </cvar>
842 <cvar name="MSVSPROJECTSUFFIX">
843 <summary>
844 <para>
845 The suffix used for &MSVC; project (DSP)
846 files. The default value is
847 <filename>.vcxproj</filename> when using Visual Studio 2010
848 and later, <filename>.vcproj</filename>
849 when using Visual Studio versions between 2002 and 2008,
850 and <filename>.dsp</filename> when using Visual Studio 6.0.
851 </para>
852 </summary>
853 </cvar>
854 <cvar name="MSVSREBUILDCOM">
855 <summary>
856 <para>
857 The rebuild command line placed in a generated &MSVC;
858 project file. The default is to have Visual
859 Studio invoke &SCons; with any specified rebuild targets.
861 </para>
862 </summary>
863 </cvar>
864 <cvar name="MSVSSCONS">
865 <summary>
866 <para>
867 The &SCons; used in generated &MSVC; project
868 files. The default is the version of &SCons; being used to
869 generate the project file.
870 </para>
871 </summary>
872 </cvar>
873 <cvar name="MSVSSCONSFLAGS">
874 <summary>
875 <para>
876 The &SCons; flags used in generated &MSVC; project files.
877 </para>
878 </summary>
879 </cvar>
880 <cvar name="MSVSSCONSCOM">
881 <summary>
882 <para>
883 The default &SCons; command used in generated &MSVC; project files.
884 </para>
885 </summary>
886 </cvar>
887 <cvar name="MSVSSCONSCRIPT">
888 <summary>
889 <para>
890 The sconscript file (that is, &SConstruct; or &SConscript;
891 file) that will be invoked by &MSVC; project files
892 (through the &cv-link-MSVSSCONSCOM; variable). The default
893 is the same sconscript file that contains the call to
894 &b-link-MSVSProject; to build the project file.
895 </para>
896 </summary>
897 </cvar>
898 <cvar name="MSVSSOLUTIONCOM">
899 <summary>
900 <para>The action used to generate Microsoft Visual Studio solution files.</para>
901 </summary>
902 </cvar> <cvar name="MSVSSOLUTIONSUFFIX">
903 <summary>
904 <para>
905 The suffix used for Microsoft Visual Studio solution (DSW)
906 files. The default value is <filename>.sln</filename>
907 when using Visual Studio version 7.x (.NET 2002) and later,
908 and <filename>.dsw</filename> when using Visual Studio 6.0.
909 </para>
910 </summary>
911 </cvar>
912 <cvar name="SCONS_HOME">
913 <summary>
914 <para>
915 The (optional) path to the &SCons; library directory,
916 initialized from the external environment. If set, this is
917 used to construct a shorter and more efficient search path in
918 the &cv-link-MSVSSCONS; command line executed from C++
919 project files.
920 </para>
921 </summary>
922 </cvar>
923 </sconsdoc>