src/engine/SCons/Tool/msvs.xml

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