src/engine/SCons/Tool/msvc.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="msvc">
   8 <summary>
   9 Sets construction variables for the Microsoft Visual C/C++ compiler.
  10 </summary>
  11 <sets>
  12 CCPDBFLAGS
  13 CCPCHFLAGS
  14 <!--CCCOMFLAGS-->
  15 CC
  16 CCFLAGS
  17 CFLAGS
  18 CCCOM
  19 SHCC
  20 SHCCFLAGS
  21 SHCFLAGS
  22 SHCCCOM
  23 CXX
  24 CXXFLAGS
  25 CXXCOM
  26 SHCXX
  27 SHCXXFLAGS
  28 SHCXXCOM
  29 CPPDEFPREFIX
  30 CPPDEFSUFFIX
  31 INCPREFIX
  32 INCSUFFIX
  33 <!--STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME-->
  34 RC
  35 RCFLAGS
  36 RCCOM
  37 BUILDERS
  38 OBJPREFIX
  39 OBJSUFFIX
  40 SHOBJPREFIX
  41 SHOBJSUFFIX
  42 CFILESUFFIX
  43 CXXFILESUFFIX
  44 PCHPDBFLAGS
  45 PCHCOM
  46 </sets>
  47 <uses>
  48 CCCOMSTR
  49 SHCCCOMSTR
  50 CXXCOMSTR
  51 SHCXXCOMSTR
  52 PCH
  53 PCHSTOP
  54 PDB
  55 </uses>
  56 </tool>
  57
  58 <builder name="PCH">
  59 <summary>
  60 Builds a Microsoft Visual C++ precompiled header.
  61 Calling this builder method
  62 returns a list of two targets: the PCH as the first element, and the object
  63 file as the second element. Normally the object file is ignored.
  64 This builder method is only
  65 provided when Microsoft Visual C++ is being used as the compiler.
  66 The PCH builder method is generally used in
  67 conjuction with the PCH construction variable to force object files to use
  68 the precompiled header:
  69
  70 <example>
  71 env['PCH'] = env.PCH('StdAfx.cpp')[0]
  72 </example>
  73 </summary>
  74 </builder>
  75
  76 <builder name="RES">
  77 <summary>
  78 Builds a Microsoft Visual C++ resource file.
  79 This builder method is only provided
  80 when Microsoft Visual C++ or MinGW is being used as the compiler. The
  81 <filename>.res</filename>
  82 (or
  83 <filename>.o</filename>
  84 for MinGW) suffix is added to the target name if no other suffix is given.
  85 The source
  86 file is scanned for implicit dependencies as though it were a C file.
  87 Example:
  88
  89 <example>
  90 env.RES('resource.rc')
  91 </example>
  92 </summary>
  93 </builder>
  94
  95 <cvar name="CCPCHFLAGS">
  96 <summary>
  97 Options added to the compiler command line
  98 to support building with precompiled headers.
  99 The default value expands expands to the appropriate
 100 Microsoft Visual C++ command-line options
 101 when the &cv-link-PCH; construction variable is set.
 102 </summary>
 103 </cvar>
 104
 105 <cvar name="CCPDBFLAGS">
 106 <summary>
 107 Options added to the compiler command line
 108 to support storing debugging information in a
 109 Microsoft Visual C++ PDB file.
 110 The default value expands expands to appropriate
 111 Microsoft Visual C++ command-line options
 112 when the &cv-link-PDB; construction variable is set.
 113
 114 The Visual C++ compiler option that SCons uses by default
 115 to generate PDB information is <option>/Z7</option>.
 116 This works correctly with parallel (<option>-j</option>) builds
 117 because it embeds the debug information in the intermediate object files,
 118 as opposed to sharing a single PDB file between multiple object files.
 119 This is also the only way to get debug information
 120 embedded into a static library.
 121 Using the <option>/Zi</option> instead may yield improved
 122 link-time performance,
 123 although parallel builds will no longer work.
 124
 125 You can generate PDB files with the <option>/Zi</option>
 126 switch by overriding the default &cv-link-CCPDBFLAGS; variable as follows:
 127
 128 <example>
 129 env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
 130 </example>
 131
 132 An alternative would be to use the <option>/Zi</option>
 133 to put the debugging information in a separate <filename>.pdb</filename>
 134 file for each object file by overriding
 135 the &cv-link-CCPDBFLAGS; variable as follows:
 136
 137 <example>
 138 env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
 139 </example>
 140 </summary>
 141 </cvar>
 142
 143 <cvar name="MSVC_BATCH">
 144 <summary>
 145 When set to any true value,
 146 specifies that &SCons; should batch
 147 compilation of object files
 148 when calling the Microsoft Visual C/C++ compiler.
 149 All compilations of source files from the same source directory
 150 that generate target files in a same output directory
 151 and were configured in &SCons; using the same construction environment
 152 will be built in a single call to the compiler.
 153 Only source files that have changed since their
 154 object files were built will be passed to each compiler invocation
 155 (via the &cv-link-CHANGED_SOURCES; construction variable).
 156 Any compilations where the object (target) file base name
 157 (minus the <filename>.obj</filename>)
 158 does not match the source file base name
 159 will be compiled separately.
 160 </summary>
 161 </cvar>
 162
 163 <cvar name="PCH">
 164 <summary>
 165 The Microsoft Visual C++ precompiled header that will be used when compiling
 166 object files. This variable is ignored by tools other than Microsoft Visual C++.
 167 When this variable is
 168 defined SCons will add options to the compiler command line to
 169 cause it to use the precompiled header, and will also set up the
 170 dependencies for the PCH file.
 171 Example:
 172
 173 <example>
 174 env['PCH'] = 'StdAfx.pch'
 175 </example>
 176 </summary>
 177 </cvar>
 178
 179 <cvar name="PCHCOM">
 180 <summary>
 181 The command line used by the
 182 &b-PCH;
 183 builder to generated a precompiled header.
 184 </summary>
 185 </cvar>
 186
 187 <cvar name="PCHCOMSTR">
 188 <summary>
 189 The string displayed when generating a precompiled header.
 190 If this is not set, then &cv-link-PCHCOM; (the command line) is displayed.
 191 </summary>
 192 </cvar>
 193
 194 <cvar name="PCHPDBFLAGS">
 195 <summary>
 196 A construction variable that, when expanded,
 197 adds the <literal>/yD</literal> flag to the command line
 198 only if the &cv-PDB; construction variable is set.
 199 </summary>
 200 </cvar>
 201
 202 <cvar name="PCHSTOP">
 203 <summary>
 204 This variable specifies how much of a source file is precompiled. This
 205 variable is ignored by tools other than Microsoft Visual C++, or when
 206 the PCH variable is not being used. When this variable is define it
 207 must be a string that is the name of the header that
 208 is included at the end of the precompiled portion of the source files, or
 209 the empty string if the "#pragma hrdstop" construct is being used:
 210
 211 <example>
 212 env['PCHSTOP'] = 'StdAfx.h'
 213 </example>
 214 </summary>
 215 </cvar>
 216
 217 <cvar name="RC">
 218 <summary>
 219 The resource compiler used to build
 220 a Microsoft Visual C++ resource file.
 221 </summary>
 222 </cvar>
 223
 224 <cvar name="RCCOM">
 225 <summary>
 226 The command line used to build
 227 a Microsoft Visual C++ resource file.
 228 </summary>
 229 </cvar>
 230
 231 <cvar name="RCCOMSTR">
 232 <summary>
 233 The string displayed when invoking the resource compiler
 234 to build a Microsoft Visual C++ resource file.
 235 If this is not set, then &cv-link-RCCOM; (the command line) is displayed.
 236 </summary>
 237 </cvar>
 238
 239 <cvar name="RCFLAGS">
 240 <summary>
 241 The flags passed to the resource compiler by the RES builder.
 242 </summary>
 243 </cvar>
 244
 245 <cvar name="RCINCFLAGS">
 246 <summary>
 247 An automatically-generated construction variable
 248 containing the command-line options
 249 for specifying directories to be searched
 250 by the resource compiler.
 251 The value of &cv-RCINCFLAGS; is created
 252 by appending &cv-RCINCPREFIX; and &cv-RCINCSUFFIX;
 253 to the beginning and end
 254 of each directory in &cv-CPPPATH;.
 255 </summary>
 256 </cvar>
 257
 258 <cvar name="RCINCPREFIX">
 259 <summary>
 260 The prefix (flag) used to specify an include directory
 261 on the resource compiler command line.
 262 This will be appended to the beginning of each directory
 263 in the &cv-CPPPATH; construction variable
 264 when the &cv-RCINCFLAGS; variable is expanded.
 265 </summary>
 266 </cvar>
 267
 268 <cvar name="RCINCSUFFIX">
 269 <summary>
 270 The suffix used to specify an include directory
 271 on the resource compiler command line.
 272 This will be appended to the end of each directory
 273 in the &cv-CPPPATH; construction variable
 274 when the &cv-RCINCFLAGS; variable is expanded.
 275 </summary>
 276 </cvar>
 277
 278 <cvar name="MSVC_VERSION">
 279 <summary>
 280 Sets the preferred  version of Microsoft Visual C/C++ to use.
 281
 282 If &cv-MSVC_VERSION; is not set,
 283 &SCons; will (by default) select the latest version
 284 of Visual C/C++ installed on your system.
 285 If the specified version isn't installed,
 286 tool initialization will fail.
 287 </summary>
 288 </cvar>