SCons/Tool/mslink.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 __COPYRIGHT__
   4
   5 This file is processed by the bin/SConsDoc.py module.
   6 See its __doc__ string for a discussion of the format.
   7 -->
   8
   9 <!DOCTYPE sconsdoc [
  10 <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
  11 %scons;
  12 <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
  13 %builders-mod;
  14 <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
  15 %functions-mod;
  16 <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
  17 %tools-mod;
  18 <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
  19 %variables-mod;
  20 ]>
  21
  22 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  23           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  24           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  25
  26 <tool name="mslink">
  27 <summary>
  28 <para>
  29 Sets construction variables for the Microsoft linker.
  30 </para>
  31 </summary>
  32 <sets>
  33 <item>SHLINK</item>
  34 <item>SHLINKFLAGS</item>
  35 <item>SHLINKCOM</item>
  36 <item>LINK</item>
  37 <item>LINKFLAGS</item>
  38 <item>LINKCOM</item>
  39 <item>LIBDIRPREFIX</item>
  40 <item>LIBDIRSUFFIX</item>
  41 <item>LIBLINKPREFIX</item>
  42 <item>LIBLINKSUFFIX</item>
  43 <item>WINDOWSDEFPREFIX</item>
  44 <item>WINDOWSDEFSUFFIX</item>
  45 <item>WINDOWS_INSERT_DEF</item>
  46 <item>WINDOWSEXPPREFIX</item>
  47 <item>WINDOWSEXPSUFFIX</item>
  48 <item>WINDOWSSHLIBMANIFESTPREFIX</item>
  49 <item>WINDOWSSHLIBMANIFESTSUFFIX</item>
  50 <item>WINDOWSPROGMANIFESTPREFIX</item>
  51 <item>WINDOWSPROGMANIFESTSUFFIX</item>
  52 <item><!--REGSVRACTION--></item>
  53 <item>REGSVR</item>
  54 <item>REGSVRFLAGS</item>
  55 <item>REGSVRCOM</item>
  56 <item>LDMODULE</item>
  57 <item>LDMODULEPREFIX</item>
  58 <item>LDMODULESUFFIX</item>
  59 <item>LDMODULEFLAGS</item>
  60 <item>LDMODULECOM</item>
  61 </sets>
  62 <uses>
  63 <item>SHLINKCOMSTR</item>
  64 <item>LINKCOMSTR</item>
  65 <item>REGSVRCOMSTR</item>
  66 <item>LDMODULECOMSTR</item>
  67 </uses>
  68 </tool>
  69
  70 <cvar name="no_import_lib">
  71 <summary>
  72 <para>
  73 When set to non-zero,
  74 suppresses creation of a corresponding Windows static import lib by the
  75 &b-link-SharedLibrary;
  76 builder when used with
  77 MinGW, Microsoft Visual Studio or Metrowerks.
  78 This also suppresses creation
  79 of an export (<filename>.exp</filename>) file
  80 when using Microsoft Visual Studio.
  81 </para>
  82 </summary>
  83 </cvar>
  84
  85 <cvar name="PDB">
  86 <summary>
  87 <para>
  88 The Microsoft Visual C++ PDB file that will store debugging information for
  89 object files, shared libraries, and programs. This variable is ignored by
  90 tools other than Microsoft Visual C++.
  91 When this variable is
  92 defined SCons will add options to the compiler and linker command line to
  93 cause them to generate external debugging information, and will also set up the
  94 dependencies for the PDB file.
  95 Example:
  96 </para>
  97
  98 <example_commands>
  99 env['PDB'] = 'hello.pdb'
 100 </example_commands>
 101
 102 <para>
 103 The Visual C++ compiler switch that SCons uses by default
 104 to generate PDB information is <option>/Z7</option>.
 105 This works correctly with parallel (<option>-j</option>) builds
 106 because it embeds the debug information in the intermediate object files,
 107 as opposed to sharing a single PDB file between multiple object files.
 108 This is also the only way to get debug information
 109 embedded into a static library.
 110 Using the <option>/Zi</option> instead may yield improved
 111 link-time performance,
 112 although parallel builds will no longer work.
 113 You can generate PDB files with the <option>/Zi</option>
 114 switch by overriding the default &cv-link-CCPDBFLAGS; variable;
 115 see the entry for that variable for specific examples.
 116 </para>
 117 </summary>
 118 </cvar>
 119
 120 <cvar name="WINDOWS_EMBED_MANIFEST">
 121 <summary>
 122 <para>
 123 Set to <constant>True</constant> to embed the
 124 compiler-generated manifest
 125 (normally <literal>${TARGET}.manifest</literal>)
 126 into all Windows executables and DLLs built with this environment,
 127 as a resource during their link step.
 128 This is done using &cv-link-MT; and &cv-link-MTEXECOM; and &cv-link-MTSHLIBCOM;.
 129 See also &cv-link-WINDOWS_INSERT_MANIFEST;.
 130 </para>
 131 </summary>
 132 </cvar>
 133
 134 <cvar name="MT">
 135 <summary>
 136 <para>
 137 The program used on Windows systems to embed manifests into DLLs and EXEs.
 138 See also &cv-link-WINDOWS_EMBED_MANIFEST;.
 139 </para>
 140 </summary>
 141 </cvar>
 142
 143 <cvar name="MTFLAGS">
 144 <summary>
 145 <para>
 146 Flags passed to the &cv-link-MT; manifest embedding program (Windows only).
 147 </para>
 148 </summary>
 149 </cvar>
 150
 151 <cvar name="MTEXECOM">
 152 <summary>
 153 <para>
 154 The Windows command line used to embed manifests into executables.
 155 See also &cv-link-MTSHLIBCOM;.
 156 </para>
 157 </summary>
 158 </cvar>
 159
 160 <cvar name="MTSHLIBCOM">
 161 <summary>
 162 <para>
 163 The Windows command line used to embed manifests into shared libraries (DLLs).
 164 See also &cv-link-MTEXECOM;.
 165 </para>
 166 </summary>
 167 </cvar>
 168
 169 <cvar name="REGSVR">
 170 <summary>
 171 <para>
 172 The program used on Windows systems
 173 to register a newly-built DLL library
 174 whenever the &b-link-SharedLibrary; builder
 175 is passed a keyword argument of <literal>register=True</literal>.
 176 </para>
 177 </summary>
 178 </cvar>
 179
 180 <cvar name="REGSVRCOM">
 181 <summary>
 182 <para>
 183 The command line used on Windows systems
 184 to register a newly-built DLL library
 185 whenever the &b-link-SharedLibrary; builder
 186 is passed a keyword argument of <literal>register=True</literal>.
 187 </para>
 188 </summary>
 189 </cvar>
 190
 191 <cvar name="REGSVRCOMSTR">
 192 <summary>
 193 <para>
 194 The string displayed when registering a newly-built DLL file.
 195 If this is not set, then &cv-link-REGSVRCOM; (the command line) is displayed.
 196 </para>
 197 </summary>
 198 </cvar>
 199
 200 <cvar name="REGSVRFLAGS">
 201 <summary>
 202 <para>
 203 Flags passed to the DLL registration program
 204 on Windows systems when a newly-built DLL library is registered.
 205 By default,
 206 this includes the <option>/s</option>
 207 that prevents dialog boxes from popping up
 208 and requiring user attention.
 209 </para>
 210 </summary>
 211 </cvar>
 212
 213 <cvar name="WINDOWS_INSERT_DEF">
 214 <summary>
 215 <para>
 216 If set to true,
 217 a library build of a Windows shared library
 218 (<filename>.dll</filename> file)
 219 will include a reference to the corresponding
 220 module-definition file at the same time,
 221 if a module-definition file
 222 is not already listed as a build target.
 223 The name of the module-definition file will
 224 be constructed from the base name of the library
 225 and the &consvars;
 226 &cv-link-WINDOWSDEFSUFFIX; and
 227 &cv-link-WINDOWSDEFPREFIX;.
 228 The default is to not add a module-definition file.
 229 The module-definition file is not created by this directive,
 230 and must be supplied by the developer.
 231 </para>
 232 </summary>
 233 </cvar>
 234
 235 <cvar name="WINDOWS_INSERT_MANIFEST">
 236 <summary>
 237 <para>
 238 If set to true,
 239 &scons;
 240 will add the manifest file
 241 generated by Microsoft Visual C++ 8.0 and later
 242 to the target list so &SCons; will be aware they
 243 were generated.
 244 In the case of an executable, the manifest file name
 245 is constructed using
 246 &cv-link-WINDOWSPROGMANIFESTSUFFIX; and
 247 &cv-link-WINDOWSPROGMANIFESTPREFIX;.
 248 In the case of a shared library, the manifest file name
 249 is constructed using
 250 &cv-link-WINDOWSSHLIBMANIFESTSUFFIX; and
 251 &cv-link-WINDOWSSHLIBMANIFESTPREFIX;.
 252 See also &cv-link-WINDOWS_EMBED_MANIFEST;.
 253 </para>
 254 </summary>
 255 </cvar>
 256
 257 <cvar name="WINDOWSDEFPREFIX">
 258 <summary>
 259 <para>
 260 The prefix used for a Windows linker module-definition file name.
 261 Defaults to empty.
 262 </para>
 263 </summary>
 264 </cvar>
 265
 266 <cvar name="WINDOWSDEFSUFFIX">
 267 <summary>
 268 <para>
 269 The suffix used for a Windows linker module-definition file name.
 270 Defaults to <filename>.def</filename>.
 271 </para>
 272 </summary>
 273 </cvar>
 274
 275 <cvar name="WINDOWSEXPPREFIX">
 276 <summary>
 277 <para>
 278 The prefix used for Windows linker exports file names.
 279 Defaults to empty.
 280 </para>
 281 </summary>
 282 </cvar>
 283
 284 <cvar name="WINDOWSEXPSUFFIX">
 285 <summary>
 286 <para>
 287 The suffix used for Windows linker exports file names.
 288 Defaults to <filename>.exp</filename>.
 289 </para>
 290 </summary>
 291 </cvar>
 292
 293 <cvar name="WINDOWSPROGMANIFESTPREFIX">
 294 <summary>
 295 <para>
 296 The prefix used for executable program manifest files
 297 generated by Microsoft Visual C/C++.
 298 Defaults to empty.
 299 </para>
 300 </summary>
 301 </cvar>
 302
 303 <cvar name="WINDOWSPROGMANIFESTSUFFIX">
 304 <summary>
 305 <para>
 306 The suffix used for executable program manifest files
 307 generated by Microsoft Visual C/C++.
 308 Defaults to <filename>.manifest</filename>.
 309 </para>
 310 </summary>
 311 </cvar>
 312
 313 <cvar name="WINDOWSSHLIBMANIFESTPREFIX">
 314 <summary>
 315 <para>
 316 The prefix used for shared library manifest files
 317 generated by Microsoft Visual C/C++.
 318 Defaults to empty.
 319 </para>
 320 </summary>
 321 </cvar>
 322
 323 <cvar name="WINDOWSSHLIBMANIFESTSUFFIX">
 324 <summary>
 325 <para>
 326 The suffix used for shared library manifest files
 327 generated by Microsoft Visual C/C++.
 328 Defaults to <filename>.manifest</filename>.
 329 </para>
 330 </summary>
 331 </cvar>
 332
 333 </sconsdoc>