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="PCH">
 144 <summary>
 145 The Microsoft Visual C++ precompiled header that will be used when compiling
 146 object files. This variable is ignored by tools other than Microsoft Visual C++.
 147 When this variable is
 148 defined SCons will add options to the compiler command line to
 149 cause it to use the precompiled header, and will also set up the
 150 dependencies for the PCH file.
 151 Example:
 152
 153 <example>
 154 env['PCH'] = 'StdAfx.pch'
 155 </example>
 156 </summary>
 157 </cvar>
 158
 159 <cvar name="PCHCOM">
 160 <summary>
 161 The command line used by the
 162 &b-PCH;
 163 builder to generated a precompiled header.
 164 </summary>
 165 </cvar>
 166
 167 <cvar name="PCHCOMSTR">
 168 <summary>
 169 The string displayed when generating a precompiled header.
 170 If this is not set, then &cv-link-PCHCOM; (the command line) is displayed.
 171 </summary>
 172 </cvar>
 173
 174 <cvar name="PCHPDBFLAGS">
 175 <summary>
 176 A construction variable that, when expanded,
 177 adds the <literal>/yD</literal> flag to the command line
 178 only if the &cv-PDB; construction variable is set.
 179 </summary>
 180 </cvar>
 181
 182 <cvar name="PCHSTOP">
 183 <summary>
 184 This variable specifies how much of a source file is precompiled. This
 185 variable is ignored by tools other than Microsoft Visual C++, or when
 186 the PCH variable is not being used. When this variable is define it
 187 must be a string that is the name of the header that
 188 is included at the end of the precompiled portion of the source files, or
 189 the empty string if the "#pragma hrdstop" construct is being used:
 190
 191 <example>
 192 env['PCHSTOP'] = 'StdAfx.h'
 193 </example>
 194 </summary>
 195 </cvar>
 196
 197 <cvar name="RC">
 198 <summary>
 199 The resource compiler used to build
 200 a Microsoft Visual C++ resource file.
 201 </summary>
 202 </cvar>
 203
 204 <cvar name="RCCOM">
 205 <summary>
 206 The command line used to build
 207 a Microsoft Visual C++ resource file.
 208 </summary>
 209 </cvar>
 210
 211 <cvar name="RCCOMSTR">
 212 <summary>
 213 The string displayed when invoking the resource compiler
 214 to build a Microsoft Visual C++ resource file.
 215 If this is not set, then &cv-link-RCCOM; (the command line) is displayed.
 216 </summary>
 217 </cvar>
 218
 219 <cvar name="RCFLAGS">
 220 <summary>
 221 The flags passed to the resource compiler by the RES builder.
 222 </summary>
 223 </cvar>
 224
 225 <cvar name="RCINCFLAGS">
 226 <summary>
 227 An automatically-generated construction variable
 228 containing the command-line options
 229 for specifying directories to be searched
 230 by the resource compiler.
 231 The value of &cv-RCINCFLAGS; is created
 232 by appending &cv-RCINCPREFIX; and &cv-RCINCSUFFIX;
 233 to the beginning and end
 234 of each directory in &cv-CPPPATH;.
 235 </summary>
 236 </cvar>
 237
 238 <cvar name="RCINCPREFIX">
 239 <summary>
 240 The prefix (flag) used to specify an include directory
 241 on the resource compiler command line.
 242 This will be appended to the beginning of each directory
 243 in the &cv-CPPPATH; construction variable
 244 when the &cv-RCINCFLAGS; variable is expanded.
 245 </summary>
 246 </cvar>
 247
 248 <cvar name="RCINCSUFFIX">
 249 <summary>
 250 The suffix used to specify an include directory
 251 on the resource compiler command line.
 252 This will be appended to the end of each directory
 253 in the &cv-CPPPATH; construction variable
 254 when the &cv-RCINCFLAGS; variable is expanded.
 255 </summary>
 256 </cvar>