src/engine/SCons/Tool/msvs.xml

   1 <!--
   2 __COPYRIGHT__
   3
   4 This file is processed by the bin/SConsDoc.py module.
   5 See its __doc__ string for a discussion of the format.
   6 -->
   7 <tool name="msvs">
   8 <summary>
   9 Sets construction variables for Microsoft Visual Studio.
  10 </summary>
  11 <sets>
  12 MSVSPROJECTCOM
  13 MSVSSOLUTIONCOM
  14 MSVSSCONSCRIPT
  15 MSVSSCONS
  16 MSVSSCONSFLAGS
  17 MSVSSCONSCOM
  18 MSVSBUILDCOM
  19 MSVSREBUILDCOM
  20 MSVSCLEANCOM
  21 MSVSENCODING
  22 </sets>
  23 <uses>
  24 </uses>
  25 </tool>
  26
  27 <builder name ="MSVSProject">
  28 <summary>
  29 Builds a Microsoft Visual Studio project file,
  30 and by default builds a solution file as well.
  31
  32 This builds a Visual Studio project file, based on the version of
  33 Visual Studio that is configured (either the latest installed version,
  34 or the version specified by
  35 &cv-link-MSVS_VERSION;
  36 in the Environment constructor).
  37 For Visual Studio 6, it will generate a
  38 <filename>.dsp</filename>
  39 file.
  40 For Visual Studio 7 (.NET) and later versions, it will generate a
  41 <filename>.vcproj</filename>
  42 file.
  43
  44 By default,
  45 this also generates a solution file
  46 for the specified project,
  47 a
  48 <filename>.dsw</filename>
  49 file for Visual Studio 6
  50 or a
  51 <filename>.sln</filename>
  52 file for Visual Studio 7 (.NET).
  53 This behavior may be disabled by specifying
  54 <literal>auto_build_solution=0</literal>
  55 when you call
  56 &b-MSVSProject;,
  57 in which case you presumably want to
  58 build the solution file(s)
  59 by calling the
  60 &b-MSVSSolution;
  61 Builder (see below).
  62
  63 It takes several lists of filenames to be placed into the project
  64 file.
  65 These are currently limited to
  66 <literal>srcs</literal>,
  67 <literal>incs</literal>,
  68 <literal>localincs</literal>,
  69 <literal>resources</literal>,
  70 and
  71 <literal>misc</literal>.
  72 These are pretty self-explanatory, but it should be noted that these
  73 lists are added to the &cv-link-SOURCES; construction variable as strings,
  74 NOT as SCons File Nodes.  This is because they represent file
  75 names to be added to the project file, not the source files used to
  76 build the project file.
  77
  78 The above filename lists are all optional,
  79 although at least one must be specified
  80 for the resulting project file to be non-empty.
  81
  82 In addition to the above lists of values,
  83 the following values may be specified:
  84
  85 <literal>target</literal>:
  86 The name of the target
  87 <filename>.dsp</filename>
  88 or
  89 <filename>.vcproj</filename>
  90 file.
  91 The correct
  92 suffix for the version of Visual Studio must be used,
  93 but the
  94 &cv-link-MSVSPROJECTSUFFIX;
  95 construction variable
  96 will be defined to the correct value (see example below).
  97
  98 <literal>variant</literal>:
  99 The name of this particular variant.
 100 For Visual Studio 7 projects,
 101 this can also be a list of variant names.
 102 These are typically things like "Debug" or "Release", but really
 103 can be anything you want.
 104 For Visual Studio 7 projects,
 105 they may also specify a target platform
 106 separated from the variant name by a
 107 <literal>|</literal>
 108 (vertical pipe)
 109 character:
 110 <literal>Debug|Xbox</literal>.
 111 The default target platform is Win32.
 112 Multiple calls to
 113 &b-MSVSProject;
 114 with different variants are allowed;
 115 all variants will be added to the project file with their appropriate
 116 build targets and sources.
 117
 118 <literal>buildtarget</literal>:
 119 An optional string, node, or list of strings or nodes
 120 (one per build variant), to tell the Visual Studio debugger
 121 what output target to use in what build variant.
 122 The number of
 123 <literal>buildtarget</literal>
 124 entries must match the number of
 125 <literal>variant</literal>
 126 entries.
 127
 128 <literal>runfile</literal>:
 129 The name of the file that Visual Studio 7 and later
 130 will run and debug.
 131 This appears as the value of the
 132 <literal>Output</literal>
 133 field in the resutling Visual Studio project file.
 134 If this is not specified,
 135 the default is the same as the specified
 136 <literal>buildtarget</literal>
 137 value.
 138
 139 Example usage:
 140
 141 <example>
 142 barsrcs = ['bar.cpp'],
 143 barincs = ['bar.h'],
 144 barlocalincs = ['StdAfx.h']
 145 barresources = ['bar.rc','resource.h']
 146 barmisc = ['bar_readme.txt']
 147
 148 dll = env.SharedLibrary(target = 'bar.dll',
 149                         source = barsrcs)
 150
 151 env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
 152                 srcs = barsrcs,
 153                 incs = barincs,
 154                 localincs = barlocalincs,
 155                 resources = barresources,
 156                 misc = barmisc,
 157                 buildtarget = dll,
 158                 variant = 'Release')
 159 </example>
 160 </summary>
 161 </builder>
 162
 163 <builder name ="MSVSSolution">
 164 <summary>
 165 Builds a Microsoft Visual Studio solution file.
 166
 167 This builds a Visual Studio solution file,
 168 based on the version of Visual Studio that is configured
 169 (either the latest installed version,
 170 or the version specified by
 171 &cv-link-MSVS_VERSION;
 172 in the construction environment).
 173 For Visual Studio 6, it will generate a
 174 <filename>.dsw</filename>
 175 file.
 176 For Visual Studio 7 (.NET), it will
 177 generate a
 178 <filename>.sln</filename>
 179 file.
 180
 181 The following values must be specified:
 182
 183 <literal>target</literal>:
 184 The name of the target .dsw or .sln file.  The correct
 185 suffix for the version of Visual Studio must be used, but the value
 186 &cv-link-MSVSSOLUTIONSUFFIX;
 187 will be defined to the correct value (see example below).
 188
 189 <literal>variant</literal>:
 190 The name of this particular variant, or a list of variant
 191 names (the latter is only supported for MSVS 7 solutions). These are
 192 typically things like "Debug" or "Release", but really can be anything
 193 you want. For MSVS 7 they may also specify target platform, like this
 194 "Debug|Xbox". Default platform is Win32.
 195
 196 <literal>projects</literal>:
 197 A list of project file names, or Project nodes returned by calls to the
 198 &b-MSVSProject;
 199 Builder,
 200 to be placed into the solution file.
 201 It should be noted that these file names are NOT added to the $SOURCES
 202 environment variable in form of files, but rather as strings.   This
 203 is because they represent file names to be added to the solution file,
 204 not the source files used to build the solution file.
 205
 206 (NOTE: Currently only one project is supported per solution.)
 207
 208 Example Usage:
 209
 210 <example>
 211 env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
 212                  projects = ['bar' + env['MSVSPROJECTSUFFIX']],
 213                  variant = 'Release')
 214 </example>
 215 </summary>
 216 </builder>
 217
 218 <cvar name="MSVS">
 219 <summary>
 220 When the Microsoft Visual Studio tools are initialized, they set up
 221 this dictionary with the following keys:
 222
 223 <envar>VERSION</envar>:
 224 the version of MSVS being used (can be set via
 225 MSVS_VERSION)
 226
 227 <envar>VERSIONS</envar>:
 228 the available versions of MSVS installed
 229
 230 <envar>VCINSTALLDIR</envar>:
 231 installed directory of Visual C++
 232
 233 <envar>VSINSTALLDIR</envar>:
 234 installed directory of Visual Studio
 235
 236 <envar>FRAMEWORKDIR</envar>:
 237 installed directory of the .NET framework
 238
 239 <envar>FRAMEWORKVERSIONS</envar>:
 240 list of installed versions of the .NET framework, sorted latest to oldest.
 241
 242 <envar>FRAMEWORKVERSION</envar>:
 243 latest installed version of the .NET framework
 244
 245 <envar>FRAMEWORKSDKDIR</envar>:
 246 installed location of the .NET SDK.
 247
 248 <envar>PLATFORMSDKDIR</envar>:
 249 installed location of the Platform SDK.
 250
 251 <envar>PLATFORMSDK_MODULES</envar>:
 252 dictionary of installed Platform SDK modules,
 253 where the dictionary keys are keywords for the various modules, and
 254 the values are 2-tuples where the first is the release date, and the
 255 second is the version number.
 256
 257 If a value isn't set, it wasn't available in the registry.
 258 </summary>
 259 </cvar>
 260
 261 <cvar name="MSVS_IGNORE_IDE_PATHS">
 262 <summary>
 263 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
 264 instead of the settings from the IDE.
 265
 266 For Visual Studio, SCons will (by default) automatically determine
 267 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
 268 set by the IDE.  You can override this behavior by setting these
 269 variables after Environment initialization, or by setting
 270 <envar>MSVS_IGNORE_IDE_PATHS = 1</envar>
 271 in the Environment initialization.
 272 Specifying this will not leave these unset, but will set them to a
 273 minimal set of paths needed to run the tools successfully.
 274
 275 For VS6, the mininimal set is:
 276 <example>
 277    INCLUDE:'&lt;VSDir&gt;\VC98\ATL\include;&lt;VSDir&gt;\VC98\MFC\include;&lt;VSDir&gt;\VC98\include'
 278    LIB:'&lt;VSDir&gt;\VC98\MFC\lib;&lt;VSDir&gt;\VC98\lib'
 279    PATH:'&lt;VSDir&gt;\Common\MSDev98\bin;&lt;VSDir&gt;\VC98\bin'
 280 </example>
 281 For VS7, it is:
 282 <example>
 283    INCLUDE:'&lt;VSDir&gt;\Vc7\atlmfc\include;&lt;VSDir&gt;\Vc7\include'
 284    LIB:'&lt;VSDir&gt;\Vc7\atlmfc\lib;&lt;VSDir&gt;\Vc7\lib'
 285    PATH:'&lt;VSDir&gt;\Common7\Tools\bin;&lt;VSDir&gt;\Common7\Tools;&lt;VSDir&gt;\Vc7\bin'
 286 </example>
 287
 288 Where '&lt;VSDir&gt;' is the installed location of Visual Studio.
 289 </summary>
 290 </cvar>
 291
 292 <cvar name="MSVS_PROJECT_BASE_PATH">
 293 <summary>
 294 The string
 295 placed in a generated Microsoft Visual Studio solution file
 296 as the value of the
 297 <literal>SccProjectFilePathRelativizedFromConnection0</literal>
 298 and
 299 <literal>SccProjectFilePathRelativizedFromConnection1</literal>
 300 attributes of the
 301 <literal>GlobalSection(SourceCodeControl)</literal>
 302 section.
 303 There is no default value.
 304 </summary>
 305 </cvar>
 306
 307 <cvar name="MSVS_PROJECT_GUID">
 308 <summary>
 309 The string
 310 placed in a generated Microsoft Visual Studio project file
 311 as the value of the
 312 <literal>ProjectGUID</literal>
 313 attribute.
 314 The string is also placed in the
 315 <literal>SolutionUniqueID</literal>
 316 attribute of the
 317 <literal>GlobalSection(SourceCodeControl)</literal>
 318 section of the Microsoft Visual Studio solution file.
 319 There is no default value.
 320 </summary>
 321 </cvar>
 322
 323 <cvar name="MSVS_SCC_AUX_PATH">
 324 <summary>
 325 The path name
 326 placed in a generated Microsoft Visual Studio project file
 327 as the value of the
 328 <literal>SccAuxPath</literal>
 329 attribute
 330 if the
 331 <envar>MSVS_SCC_PROVIDER</envar>
 332 construction variable is also set.
 333 There is no default value.
 334 </summary>
 335 </cvar>
 336
 337 <cvar name="MSVS_SCC_LOCAL_PATH">
 338 <summary>
 339 The path name
 340 placed in a generated Microsoft Visual Studio project file
 341 as the value of the
 342 <literal>SccLocalPath</literal>
 343 attribute
 344 if the
 345 <envar>MSVS_SCC_PROVIDER</envar>
 346 construction variable is also set.
 347 The path name is also placed in the
 348 <literal>SccLocalPath0</literal>
 349 and
 350 <literal>SccLocalPath1</literal>
 351 attributes of the
 352 <literal>GlobalSection(SourceCodeControl)</literal>
 353 section of the Microsoft Visual Studio solution file.
 354 There is no default value.
 355 </summary>
 356 </cvar>
 357
 358 <cvar name="MSVS_SCC_PROJECT_NAME">
 359 <summary>
 360 The project name
 361 placed in a generated Microsoft Visual Studio project file
 362 as the value of the
 363 <literal>SccProjectName</literal>
 364 attribute.
 365 There is no default value.
 366 </summary>
 367 </cvar>
 368
 369 <cvar name="MSVS_SCC_PROVIDER">
 370 <summary>
 371 The string
 372 placed in a generated Microsoft Visual Studio project file
 373 as the value of the
 374 <literal>SccProvider</literal>
 375 attribute.
 376 The string is also placed in the
 377 <literal>SccProvider1</literal>
 378 attribute of the
 379 <literal>GlobalSection(SourceCodeControl)</literal>
 380 section of the Microsoft Visual Studio solution file.
 381 There is no default value.
 382 </summary>
 383 </cvar>
 384
 385 <cvar name="MSVS_USE_MFC_DIRS">
 386 <summary>
 387 Tells the MS Visual Studio tool(s) to use
 388 the MFC directories in its default paths
 389 for compiling and linking.
 390 The &cv-MSVS_USE_MFC_DIRS; variable has no effect if the
 391 <envar>INCLUDE</envar>
 392 or
 393 <envar>LIB</envar>
 394 environment variables are set explictly.
 395
 396 Under Visual Studio version 6,
 397 setting
 398 &cv-MSVS_USE_MFC_DIRS;
 399 to a non-zero value
 400 adds the
 401 <filename>ATL\include</filename>
 402 and
 403 <filename>MFC\include</filename>
 404 directories to
 405 the default
 406 <envar>INCLUDE</envar>
 407 external environment variable,
 408 and adds the
 409 <filename>MFC\lib</filename>
 410 directory to
 411 the default
 412 <envar>LIB</envar>
 413 external environment variable.
 414
 415 Under Visual Studio version 7,
 416 setting
 417 &cv-MSVS_USE_MFC_DIRS;
 418 to a non-zero value
 419 adds the
 420 <filename>atlmfc\include</filename>
 421 directory to the default
 422 <envar>INCLUDE</envar>
 423 external environment variable,
 424 and adds the
 425 <filename>atlmfc\lib</filename>
 426 directory to the default
 427 <envar>LIB</envar>
 428 external environment variable.
 429
 430 Under Visual Studio version 8,
 431 setting
 432 &cv-MSVS_USE_MFC_DIRS;
 433 to a non-zero value will,
 434 by default,
 435 add the
 436 <filename>atlmfc\include</filename>
 437 directory to the default
 438 <envar>INCLUDE</envar>
 439 external environment variable,
 440 and the
 441 <filename>atlmfc\lib</filename>
 442 directory to the default
 443 <envar>LIB</envar>
 444 external environment variable.
 445 If, however, the
 446 <envar>['MSVS']['PLATFORMSDKDIR']</envar>
 447 variable is set,
 448 then the
 449 <filename>mfc</filename>
 450 and the
 451 <filename>atl</filename>
 452 subdirectories of the
 453 <envar>PLATFORMSDKDIR</envar>
 454 are added to the default value of the
 455 <envar>INCLUDE</envar>
 456 external environment variable,
 457 and the default value of the
 458 <envar>LIB</envar>
 459 external environment variable is left untouched.
 460 </summary>
 461 </cvar>
 462
 463 <cvar name="MSVS_VERSION">
 464 <summary>
 465 Sets the preferred version of MSVS to use.
 466
 467 SCons will (by default) select the latest version of MSVS
 468 installed on your machine.
 469 So, if you have version 6 and version 7 (MSVS .NET) installed,
 470 it will prefer version 7.
 471 You can override this by
 472 specifying the
 473 <envar>MSVS_VERSION</envar>
 474 variable in the Environment initialization, setting it to the
 475 appropriate version ('6.0' or '7.0', for example).
 476 If the given version isn't installed, tool initialization will fail.
 477 </summary>
 478 </cvar>
 479
 480 <cvar name="MSVSBUILDCOM">
 481 <summary>
 482 The build command line placed in
 483 a generated Microsoft Visual Studio project file.
 484 The default is to have Visual Studio invoke SCons with any specified
 485 build targets.
 486 </summary>
 487 </cvar>
 488
 489 <cvar name="MSVSCLEANCOM">
 490 <summary>
 491 The clean command line placed in
 492 a generated Microsoft Visual Studio project file.
 493 The default is to have Visual Studio invoke SCons with the -c option
 494 to remove any specified targets.
 495 </summary>
 496 </cvar>
 497
 498 <cvar name="MSVSENCODING">
 499 <summary>
 500 The encoding string placed in
 501 a generated Microsoft Visual Studio project file.
 502 The default is encoding
 503 <literal>Windows-1252</literal>.
 504 </summary>
 505 </cvar>
 506
 507 <cvar name="MSVSPROJECTCOM">
 508 <summary>
 509 The action used to generate Microsoft Visual Studio project files.
 510 </summary>
 511 </cvar>
 512
 513 <cvar name="MSVSPROJECTSUFFIX">
 514 <summary>
 515 The suffix used for Microsoft Visual Studio project (DSP) files.
 516 The default value is
 517 <filename>.vcproj</filename>
 518 when using Visual Studio version 7.x (.NET)
 519 or later version,
 520 and
 521 <filename>.dsp</filename>
 522 when using earlier versions of Visual Studio.
 523 </summary>
 524 </cvar>
 525
 526 <cvar name="MSVSREBUILDCOM">
 527 <summary>
 528 The rebuild command line placed in
 529 a generated Microsoft Visual Studio project file.
 530 The default is to have Visual Studio invoke SCons with any specified
 531 rebuild targets.
 532 </summary>
 533 </cvar>
 534
 535 <cvar name="MSVSSCONS">
 536 <summary>
 537 The SCons used in generated Microsoft Visual Studio project files.
 538 The default is the version of SCons being
 539 used to generate the project file.
 540 </summary>
 541 </cvar>
 542
 543 <cvar name="MSVSSCONSFLAGS">
 544 <summary>
 545 The SCons flags used in generated Microsoft Visual Studio
 546 project files.
 547 </summary>
 548 </cvar>
 549
 550 <cvar name="MSVSSCONSCOM">
 551 <summary>
 552 The default SCons command used in generated Microsoft Visual Studio
 553 project files.
 554 </summary>
 555 </cvar>
 556
 557 <cvar name="MSVSSCONSCRIPT">
 558 <summary>
 559 The sconscript file
 560 (that is,
 561 &SConstruct;
 562 or
 563 &SConscript;
 564 file)
 565 that will be invoked by Visual Studio
 566 project files
 567 (through the
 568 &cv-link-MSVSSCONSCOM;
 569 variable).
 570 The default is the same sconscript file
 571 that contains the call to
 572 &b-MSVSProject;
 573 to build the project file.
 574 </summary>
 575 </cvar>
 576
 577 <cvar name="MSVSSOLUTIONCOM">
 578 <summary>
 579 The action used to generate Microsoft Visual Studio solution files.
 580 </summary>
 581 </cvar>
 582
 583 <cvar name="MSVSSOLUTIONSUFFIX">
 584 <summary>
 585 The suffix used for Microsoft Visual Studio solution (DSW) files.
 586 The default value is
 587 <filename>.sln</filename>
 588 when using Visual Studio version 7.x (.NET),
 589 and
 590 <filename>.dsw</filename>
 591 when using earlier versions of Visual Studio.
 592 </summary>
 593 </cvar>
 594
 595 <cvar name="SCONS_HOME">
 596 <summary>
 597 The (optional) path to the SCons library directory,
 598 initialized from the external environment.
 599 If set, this is used to construct a shorter and more
 600 efficient search path in the
 601 &cv-link-MSVSSCONS;
 602 command line executed
 603 from Microsoft Visual Studio project files.
 604 </summary>
 605 </cvar>