doc/generated/variables.gen

   1 <!DOCTYPE sconsdoc [
   2     <!ENTITY % scons SYSTEM "../scons.mod">
   3     %scons;
   4     <!ENTITY % builders-mod SYSTEM "builders.mod">
   5     %builders-mod;
   6     <!ENTITY % functions-mod SYSTEM "functions.mod">
   7     %functions-mod;
   8     <!ENTITY % tools-mod SYSTEM "tools.mod">
   9     %tools-mod;
  10     <!ENTITY % variables-mod SYSTEM "variables.mod">
  11     %variables-mod;
  12 ]>
  13
  14 <variablelist xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  15   <varlistentry id="cv-__LDMODULEVERSIONFLAGS">
  16     <term>
  17       <envar>__LDMODULEVERSIONFLAGS</envar>
  18     </term>
  19     <listitem><para>
  20 This construction variable automatically introduces &cv-link-_LDMODULEVERSIONFLAGS;
  21 if &cv-link-LDMODULEVERSION; is set. Othervise it evaluates to an empty string.
  22 </para>
  23 </listitem>
  24   </varlistentry>
  25   <varlistentry id="cv-__SHLIBVERSIONFLAGS">
  26     <term>
  27       <envar>__SHLIBVERSIONFLAGS</envar>
  28     </term>
  29     <listitem><para>
  30 This construction variable automatically introduces &cv-link-_SHLIBVERSIONFLAGS;
  31 if &cv-link-SHLIBVERSION; is set. Othervise it evaluates to an empty string.
  32 </para>
  33 </listitem>
  34   </varlistentry>
  35   <varlistentry id="cv-APPLELINK_COMPATIBILITY_VERSION">
  36     <term>
  37       <envar>APPLELINK_COMPATIBILITY_VERSION</envar>
  38     </term>
  39     <listitem><para>
  40                 On Mac OS X this is used to set the linker flag:
  41
  42                 -compatibility_version
  43             </para>
  44             <para>
  45                 The value is specified as X[.Y[.Z]] where X is between 1 and 65535, Y can be omitted or between 1 and
  46                 255, Z can be omitted or between 1 and 255. This value will be derived from &cv-link-SHLIBVERSION; if
  47                 not
  48                 specified. The lowest digit will be dropped and replaced by a 0.
  49             </para>
  50             <para>
  51                 If the &cv-link-APPLELINK_NO_COMPATIBILITY_VERSION; is set then no -compatibility_version will be
  52                 output.
  53             </para>
  54             <para>See MacOS's ld manpage for more details</para>
  55         </listitem>
  56   </varlistentry>
  57   <varlistentry id="cv-_APPLELINK_COMPATIBILITY_VERSION">
  58     <term>
  59       <envar>_APPLELINK_COMPATIBILITY_VERSION</envar>
  60     </term>
  61     <listitem><para>
  62                 A macro (by default a generator function) used to create the linker flags to specify
  63                 apple's linker's -compatibility_version flag.
  64                 The default generator uses &cv-link-APPLELINK_COMPATIBILITY_VERSION;
  65                 and &cv-link-APPLELINK_NO_COMPATIBILITY_VERSION; and  &cv-link-SHLIBVERSION;
  66                 to determine the correct flag.
  67             </para>
  68         </listitem>
  69   </varlistentry>
  70   <varlistentry id="cv-APPLELINK_CURRENT_VERSION">
  71     <term>
  72       <envar>APPLELINK_CURRENT_VERSION</envar>
  73     </term>
  74     <listitem><para>
  75                 On Mac OS X this is used to set the linker flag:
  76
  77                 -current_version
  78             </para>
  79             <para>
  80                 The value is specified as X[.Y[.Z]] where X is between 1 and 65535, Y can be omitted or between 1 and
  81                 255, Z can be omitted or between 1 and 255. This value will be set to &cv-link-SHLIBVERSION; if not
  82                 specified.
  83             </para>
  84             <para>
  85                 If the &cv-link-APPLELINK_NO_CURRENT_VERSION; is set then no -current_version will be
  86                 output.
  87             </para>
  88             <para>See MacOS's ld manpage for more details</para>
  89
  90         </listitem>
  91   </varlistentry>
  92   <varlistentry id="cv-_APPLELINK_CURRENT_VERSION">
  93     <term>
  94       <envar>_APPLELINK_CURRENT_VERSION</envar>
  95     </term>
  96     <listitem><para>
  97                 A macro (by default a generator function) used to create the linker flags to specify apple's linker's
  98                 -current_version flag.  The default generator uses &cv-link-APPLELINK_CURRENT_VERSION; and
  99                 &cv-link-APPLELINK_NO_CURRENT_VERSION; and  &cv-link-SHLIBVERSION; to determine the correct flag.
 100             </para>
 101         </listitem>
 102   </varlistentry>
 103   <varlistentry id="cv-APPLELINK_NO_COMPATIBILITY_VERSION">
 104     <term>
 105       <envar>APPLELINK_NO_COMPATIBILITY_VERSION</envar>
 106     </term>
 107     <listitem><para>
 108                 Set this to any True (1|True|non-empty string) value to disable adding -compatibility_version flag when
 109                 generating versioned shared libraries.
 110             </para>
 111             <para>
 112                 This overrides &cv-link-APPLELINK_COMPATIBILITY_VERSION;.
 113             </para>
 114         </listitem>
 115   </varlistentry>
 116   <varlistentry id="cv-APPLELINK_NO_CURRENT_VERSION">
 117     <term>
 118       <envar>APPLELINK_NO_CURRENT_VERSION</envar>
 119     </term>
 120     <listitem><para>
 121                 Set this to any True (1|True|non-empty string) value to disable adding -current_version flag when
 122                 generating versioned shared libraries.
 123             </para>
 124             <para>
 125                 This overrides &cv-link-APPLELINK_CURRENT_VERSION;.
 126             </para>
 127         </listitem>
 128   </varlistentry>
 129   <varlistentry id="cv-AR">
 130     <term>
 131       <envar>AR</envar>
 132     </term>
 133     <listitem><para>
 134 The static library archiver.
 135 </para>
 136 </listitem>
 137   </varlistentry>
 138   <varlistentry id="cv-ARCHITECTURE">
 139     <term>
 140       <envar>ARCHITECTURE</envar>
 141     </term>
 142     <listitem><para>
 143 Specifies the system architecture for which
 144 the package is being built.
 145 The default is the system architecture
 146 of the machine on which SCons is running.
 147 This is used to fill in the
 148 <literal>Architecture:</literal>
 149 field in an Ipkg
 150 <filename>control</filename> file,
 151 and the <literal>BuildArch:</literal> field
 152 in the RPM <filename>.spec</filename> file,
 153 as well as forming part of the name of a generated RPM package file.
 154 </para>
 155 <para>See the &b-link-Package; builder.</para>
 156 </listitem>
 157   </varlistentry>
 158   <varlistentry id="cv-ARCOM">
 159     <term>
 160       <envar>ARCOM</envar>
 161     </term>
 162     <listitem><para>
 163 The command line used to generate a static library from object files.
 164 </para>
 165 </listitem>
 166   </varlistentry>
 167   <varlistentry id="cv-ARCOMSTR">
 168     <term>
 169       <envar>ARCOMSTR</envar>
 170     </term>
 171     <listitem><para>
 172 The string displayed when a static library is
 173 generated from object files.
 174 If this is not set, then &cv-link-ARCOM; (the command line) is displayed.
 175 </para>
 176
 177 <example_commands>
 178 env = Environment(ARCOMSTR = "Archiving $TARGET")
 179 </example_commands>
 180 </listitem>
 181   </varlistentry>
 182   <varlistentry id="cv-ARFLAGS">
 183     <term>
 184       <envar>ARFLAGS</envar>
 185     </term>
 186     <listitem><para>
 187 General options passed to the static library archiver.
 188 </para>
 189 </listitem>
 190   </varlistentry>
 191   <varlistentry id="cv-AS">
 192     <term>
 193       <envar>AS</envar>
 194     </term>
 195     <listitem><para>
 196 The assembler.
 197 </para>
 198 </listitem>
 199   </varlistentry>
 200   <varlistentry id="cv-ASCOM">
 201     <term>
 202       <envar>ASCOM</envar>
 203     </term>
 204     <listitem><para>
 205 The command line used to generate an object file
 206 from an assembly-language source file.
 207 </para>
 208 </listitem>
 209   </varlistentry>
 210   <varlistentry id="cv-ASCOMSTR">
 211     <term>
 212       <envar>ASCOMSTR</envar>
 213     </term>
 214     <listitem><para>
 215 The string displayed when an object file
 216 is generated from an assembly-language source file.
 217 If this is not set, then &cv-link-ASCOM; (the command line) is displayed.
 218 </para>
 219
 220 <example_commands>
 221 env = Environment(ASCOMSTR = "Assembling $TARGET")
 222 </example_commands>
 223 </listitem>
 224   </varlistentry>
 225   <varlistentry id="cv-ASFLAGS">
 226     <term>
 227       <envar>ASFLAGS</envar>
 228     </term>
 229     <listitem><para>
 230 General options passed to the assembler.
 231 </para>
 232 </listitem>
 233   </varlistentry>
 234   <varlistentry id="cv-ASPPCOM">
 235     <term>
 236       <envar>ASPPCOM</envar>
 237     </term>
 238     <listitem><para>
 239 The command line used to assemble an assembly-language
 240 source file into an object file
 241 after first running the file through the C preprocessor.
 242 Any options specified
 243 in the &cv-link-ASFLAGS; and &cv-link-CPPFLAGS; construction variables
 244 are included on this command line.
 245 </para>
 246 </listitem>
 247   </varlistentry>
 248   <varlistentry id="cv-ASPPCOMSTR">
 249     <term>
 250       <envar>ASPPCOMSTR</envar>
 251     </term>
 252     <listitem><para>
 253 The string displayed when an object file
 254 is generated from an assembly-language source file
 255 after first running the file through the C preprocessor.
 256 If this is not set, then &cv-link-ASPPCOM; (the command line) is displayed.
 257 </para>
 258
 259 <example_commands>
 260 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
 261 </example_commands>
 262 </listitem>
 263   </varlistentry>
 264   <varlistentry id="cv-ASPPFLAGS">
 265     <term>
 266       <envar>ASPPFLAGS</envar>
 267     </term>
 268     <listitem><para>
 269 General options when an assembling an assembly-language
 270 source file into an object file
 271 after first running the file through the C preprocessor.
 272 The default is to use the value of &cv-link-ASFLAGS;.
 273 </para>
 274 </listitem>
 275   </varlistentry>
 276   <varlistentry id="cv-BIBTEX">
 277     <term>
 278       <envar>BIBTEX</envar>
 279     </term>
 280     <listitem><para>
 281 The bibliography generator for the TeX formatter and typesetter and the
 282 LaTeX structured formatter and typesetter.
 283 </para>
 284 </listitem>
 285   </varlistentry>
 286   <varlistentry id="cv-BIBTEXCOM">
 287     <term>
 288       <envar>BIBTEXCOM</envar>
 289     </term>
 290     <listitem><para>
 291 The command line used to call the bibliography generator for the
 292 TeX formatter and typesetter and the LaTeX structured formatter and
 293 typesetter.
 294 </para>
 295 </listitem>
 296   </varlistentry>
 297   <varlistentry id="cv-BIBTEXCOMSTR">
 298     <term>
 299       <envar>BIBTEXCOMSTR</envar>
 300     </term>
 301     <listitem><para>
 302 The string displayed when generating a bibliography
 303 for TeX or LaTeX.
 304 If this is not set, then &cv-link-BIBTEXCOM; (the command line) is displayed.
 305 </para>
 306
 307 <example_commands>
 308 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
 309 </example_commands>
 310 </listitem>
 311   </varlistentry>
 312   <varlistentry id="cv-BIBTEXFLAGS">
 313     <term>
 314       <envar>BIBTEXFLAGS</envar>
 315     </term>
 316     <listitem><para>
 317 General options passed to the bibliography generator for the TeX formatter
 318 and typesetter and the LaTeX structured formatter and typesetter.
 319 </para>
 320 </listitem>
 321   </varlistentry>
 322   <varlistentry id="cv-BUILDERS">
 323     <term>
 324       <envar>BUILDERS</envar>
 325     </term>
 326     <listitem><para>
 327 A dictionary mapping the names of the builders
 328 available through the &consenv; to underlying Builder objects.
 329 Custom builders need to be added to this to make them available.
 330 </para>
 331
 332 <para>
 333 A platform-dependent default list of builders such as
 334 &b-link-Program;, &b-link-Library; etc. is used to
 335 populate this &consvar; when the &consenv; is initialized
 336 via the presence/absence of the tools those builders depend on.
 337 &cv-BUILDERS; can be examined to learn which builders will
 338 actually be available at run-time.
 339 </para>
 340
 341 <para>
 342 Note that if you initialize this &consvar; through
 343 assignment when the &consenv; is created,
 344 that value for &cv-BUILDERS; will override any defaults:
 345 </para>
 346
 347 <example_commands>
 348 bld = Builder(action='foobuild &lt; $SOURCE &gt; $TARGET')
 349 env = Environment(BUILDERS={'NewBuilder': bld})
 350 </example_commands>
 351
 352 <para>
 353 To instead use a new Builder object in addition to the default Builders,
 354 add your new Builder object like this:
 355 </para>
 356
 357 <example_commands>
 358 env = Environment()
 359 env.Append(BUILDERS={'NewBuilder': bld})
 360 </example_commands>
 361
 362 <para>
 363 or this:
 364 </para>
 365
 366 <example_commands>
 367 env = Environment()
 368 env['BUILDERS']['NewBuilder'] = bld
 369 </example_commands>
 370 </listitem>
 371   </varlistentry>
 372   <varlistentry id="cv-CACHEDIR_CLASS">
 373     <term>
 374       <envar>CACHEDIR_CLASS</envar>
 375     </term>
 376     <listitem><para>
 377 The class type that SCons should use when instantiating a
 378 new &f-link-CacheDir; in this &consenv;. Must be
 379 a subclass of the <classname>SCons.CacheDir.CacheDir</classname> class.
 380         </para>
 381     </listitem>
 382   </varlistentry>
 383   <varlistentry id="cv-CC">
 384     <term>
 385       <envar>CC</envar>
 386     </term>
 387     <listitem><para>
 388 The C compiler.
 389 </para>
 390 </listitem>
 391   </varlistentry>
 392   <varlistentry id="cv-CCCOM">
 393     <term>
 394       <envar>CCCOM</envar>
 395     </term>
 396     <listitem><para>
 397 The command line used to compile a C source file to a (static) object
 398 file.  Any options specified in the &cv-link-CFLAGS;, &cv-link-CCFLAGS; and
 399 &cv-link-CPPFLAGS; construction variables are included on this command line.
 400 See also &cv-link-SHCCCOM; for compiling to shared objects.
 401 </para>
 402 </listitem>
 403   </varlistentry>
 404   <varlistentry id="cv-CCCOMSTR">
 405     <term>
 406       <envar>CCCOMSTR</envar>
 407     </term>
 408     <listitem><para>
 409 If set, the string displayed when a C source file
 410 is compiled to a (static) object file.
 411 If not set, then &cv-link-CCCOM; (the command line) is displayed.
 412 See also &cv-link-SHCCCOMSTR; for compiling to shared objects.
 413 </para>
 414
 415 <example_commands>
 416 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
 417 </example_commands>
 418 </listitem>
 419   </varlistentry>
 420   <varlistentry id="cv-CCDEPFLAGS">
 421     <term>
 422       <envar>CCDEPFLAGS</envar>
 423     </term>
 424     <listitem><para>
 425 Options to pass to C or C++ compiler to generate list of dependency files.
 426 </para>
 427  <para>
 428   This is set only by compilers which support this functionality. (&t-link-gcc;, &t-link-clang;, and &t-link-msvc; currently)
 429  </para>
 430 </listitem>
 431   </varlistentry>
 432   <varlistentry id="cv-CCFLAGS">
 433     <term>
 434       <envar>CCFLAGS</envar>
 435     </term>
 436     <listitem><para>
 437 General options that are passed to the C and C++ compilers.
 438 See also &cv-link-SHCCFLAGS; for compiling to shared objects.
 439 </para>
 440 </listitem>
 441   </varlistentry>
 442   <varlistentry id="cv-CCPCHFLAGS">
 443     <term>
 444       <envar>CCPCHFLAGS</envar>
 445     </term>
 446     <listitem><para>
 447 Options added to the compiler command line
 448 to support building with precompiled headers.
 449 The default value expands expands to the appropriate
 450 &MSVC; command-line options
 451 when the &cv-link-PCH; &consvar; is set.
 452 </para>
 453 </listitem>
 454   </varlistentry>
 455   <varlistentry id="cv-CCPDBFLAGS">
 456     <term>
 457       <envar>CCPDBFLAGS</envar>
 458     </term>
 459     <listitem><para>
 460 Options added to the compiler command line
 461 to support storing debugging information in a
 462 &MSVC; PDB file.
 463 The default value expands expands to appropriate
 464 &MSVC; command-line options
 465 when the &cv-link-PDB; &consvar; is set.
 466 </para>
 467
 468 <para>
 469 The &MSVC; compiler option that &SCons; uses by default
 470 to generate PDB information is <option>/Z7</option>.
 471 This works correctly with parallel (<option>-j</option>) builds
 472 because it embeds the debug information in the intermediate object files,
 473 as opposed to sharing a single PDB file between multiple object files.
 474 This is also the only way to get debug information
 475 embedded into a static library.
 476 Using the <option>/Zi</option> instead may yield improved
 477 link-time performance,
 478 although parallel builds will no longer work.
 479 </para>
 480
 481 <para>
 482 You can generate PDB files with the <option>/Zi</option>
 483 switch by overriding the default &cv-link-CCPDBFLAGS; variable as follows:
 484 </para>
 485
 486 <example_commands>
 487 env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
 488 </example_commands>
 489
 490 <para>
 491 An alternative would be to use the <option>/Zi</option>
 492 to put the debugging information in a separate <filename>.pdb</filename>
 493 file for each object file by overriding
 494 the &cv-link-CCPDBFLAGS; variable as follows:
 495 </para>
 496
 497 <example_commands>
 498 env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
 499 </example_commands>
 500 </listitem>
 501   </varlistentry>
 502   <varlistentry id="cv-CCVERSION">
 503     <term>
 504       <envar>CCVERSION</envar>
 505     </term>
 506     <listitem><para>
 507 The version number of the C compiler.
 508 This may or may not be set,
 509 depending on the specific C compiler being used.
 510 </para>
 511 </listitem>
 512   </varlistentry>
 513   <varlistentry id="cv-CFILESUFFIX">
 514     <term>
 515       <envar>CFILESUFFIX</envar>
 516     </term>
 517     <listitem><para>
 518 The suffix for C source files.
 519 This is used by the internal CFile builder
 520 when generating C files from Lex (.l) or YACC (.y) input files.
 521 The default suffix, of course, is
 522 <filename>.c</filename>
 523 (lower case).
 524 On case-insensitive systems (like Windows),
 525 SCons also treats
 526 <filename>.C</filename>
 527 (upper case) files
 528 as C files.
 529 </para>
 530 </listitem>
 531   </varlistentry>
 532   <varlistentry id="cv-CFLAGS">
 533     <term>
 534       <envar>CFLAGS</envar>
 535     </term>
 536     <listitem><para>
 537 General options that are passed to the C compiler (C only; not C++).
 538 See also &cv-link-SHCFLAGS; for compiling to shared objects.
 539 </para>
 540 </listitem>
 541   </varlistentry>
 542   <varlistentry id="cv-CHANGE_SPECFILE">
 543     <term>
 544       <envar>CHANGE_SPECFILE</envar>
 545     </term>
 546     <listitem><para>
 547 A hook for modifying the file that controls the packaging build
 548 (the <filename>.spec</filename> for RPM,
 549 the <filename>control</filename> for Ipkg,
 550 the <filename>.wxs</filename> for MSI).
 551 If set, the function will be called
 552 after the SCons template for the file has been written.
 553 </para>
 554 <para>See the &b-link-Package; builder.</para>
 555 </listitem>
 556   </varlistentry>
 557   <varlistentry id="cv-CHANGED_SOURCES">
 558     <term>
 559       <envar>CHANGED_SOURCES</envar>
 560     </term>
 561     <listitem><para>
 562 A reserved variable name
 563 that may not be set or used in a construction environment.
 564 (See the manpage section "Variable Substitution"
 565 for more information).
 566 </para>
 567 </listitem>
 568   </varlistentry>
 569   <varlistentry id="cv-CHANGED_TARGETS">
 570     <term>
 571       <envar>CHANGED_TARGETS</envar>
 572     </term>
 573     <listitem><para>
 574 A reserved variable name
 575 that may not be set or used in a construction environment.
 576 (See the manpage section "Variable Substitution"
 577 for more information).
 578 </para>
 579 </listitem>
 580   </varlistentry>
 581   <varlistentry id="cv-CHANGELOG">
 582     <term>
 583       <envar>CHANGELOG</envar>
 584     </term>
 585     <listitem><para>
 586 The name of a file containing the change log text
 587 to be included in the package.
 588 This is included as the
 589 <literal>%changelog</literal>
 590 section of the RPM
 591 <filename>.spec</filename> file.
 592 </para>
 593 <para>See the &b-link-Package; builder.</para>
 594 </listitem>
 595   </varlistentry>
 596   <varlistentry id="cv-COMPILATIONDB_COMSTR">
 597     <term>
 598       <envar>COMPILATIONDB_COMSTR</envar>
 599     </term>
 600     <listitem><para>
 601                 The string displayed when the &b-link-CompilationDatabase;
 602                 builder's action is run.
 603             </para>
 604         </listitem>
 605   </varlistentry>
 606   <varlistentry id="cv-COMPILATIONDB_PATH_FILTER">
 607     <term>
 608       <envar>COMPILATIONDB_PATH_FILTER</envar>
 609     </term>
 610     <listitem><para>
 611                 A string which instructs &b-link-CompilationDatabase; to
 612                 only include entries where the <literal>output</literal> member
 613                 matches the pattern in the filter string using fnmatch, which
 614                 uses glob style wildcards.
 615
 616             </para>
 617             <para>
 618                 The default value is an empty string '', which disables filtering.
 619             </para>
 620         </listitem>
 621   </varlistentry>
 622   <varlistentry id="cv-COMPILATIONDB_USE_ABSPATH">
 623     <term>
 624       <envar>COMPILATIONDB_USE_ABSPATH</envar>
 625     </term>
 626     <listitem><para>
 627                 A boolean flag to instruct &b-link-CompilationDatabase;
 628                 whether to write the <literal>file</literal> and
 629                 <literal>output</literal> members
 630                 in the compilation database using absolute or relative paths.
 631             </para>
 632             <para>
 633                 The default value is False (use relative paths)
 634             </para>
 635         </listitem>
 636   </varlistentry>
 637   <varlistentry id="cv-_concat">
 638     <term>
 639       <envar>_concat</envar>
 640     </term>
 641     <listitem><para>
 642         A function used to produce variables like &cv-link-_CPPINCFLAGS;. It takes
 643         four mandatory arguments, and up to 4 additional optional arguments:
 644         1) a prefix to concatenate onto each element,
 645         2) a list of elements,
 646         3) a suffix to concatenate onto each element,
 647         4) an environment for variable interpolation,
 648         5) an optional function that will be called to transform the list before concatenation,
 649         6) an optionally specified target (Can use TARGET),
 650         7) an optionally specified source (Can use SOURCE),
 651         8) optional <parameter>affect_signature</parameter> flag which will wrap non-empty returned value with $( and $) to indicate the contents
 652         should not affect the signature of the generated command line.
 653     </para>
 654
 655     <example_commands>
 656         env['_CPPINCFLAGS'] = '${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE, affect_signature=False)}'
 657     </example_commands>
 658 </listitem>
 659   </varlistentry>
 660   <varlistentry id="cv-CONFIGUREDIR">
 661     <term>
 662       <envar>CONFIGUREDIR</envar>
 663     </term>
 664     <listitem><para>
 665 The name of the directory in which
 666 Configure context test files are written.
 667 The default is
 668 <filename>.sconf_temp</filename>
 669 in the top-level directory
 670 containing the
 671 <filename>SConstruct</filename>
 672 file.
 673 </para>
 674 <para>
 675 If variant directories are in use,
 676 and the configure check results should not be
 677 shared between variants,
 678 you can set &cv-CONFIGUREDIR;
 679 and &cv-link-CONFIGURELOG; so they are
 680 unique per variant directory.
 681 </para>
 682 </listitem>
 683   </varlistentry>
 684   <varlistentry id="cv-CONFIGURELOG">
 685     <term>
 686       <envar>CONFIGURELOG</envar>
 687     </term>
 688     <listitem><para>
 689 The name of the &Configure; context log file.
 690 The default is
 691 <filename>config.log</filename>
 692 in the top-level directory
 693 containing the
 694 <filename>SConstruct</filename>
 695 file.
 696 </para>
 697 <para>
 698 If variant directories are in use,
 699 and the configure check results should not be
 700 shared between variants,
 701 you can set &cv-link-CONFIGUREDIR;
 702 and &cv-CONFIGURELOG; so they are
 703 unique per variant directory.
 704 </para>
 705 </listitem>
 706   </varlistentry>
 707   <varlistentry id="cv-_CPPDEFFLAGS">
 708     <term>
 709       <envar>_CPPDEFFLAGS</envar>
 710     </term>
 711     <listitem><para>
 712 An automatically-generated &consvar;
 713 containing the C preprocessor command-line options
 714 to define values.
 715 The value of &cv-link-_CPPDEFFLAGS; is created
 716 by respectively prepending and appending
 717 &cv-link-CPPDEFPREFIX; and &cv-link-CPPDEFSUFFIX;
 718 to each definition in &cv-link-CPPDEFINES;.
 719 </para>
 720 </listitem>
 721   </varlistentry>
 722   <varlistentry id="cv-CPPDEFINES">
 723     <term>
 724       <envar>CPPDEFINES</envar>
 725     </term>
 726     <listitem><para>
 727 A platform independent specification of C preprocessor macro definitions.
 728 The definitions are added to command lines
 729 through the automatically-generated
 730 &cv-link-_CPPDEFFLAGS; &consvar;,
 731 which is constructed according to
 732 the contents of &cv-CPPDEFINES;:
 733 </para>
 734
 735 <itemizedlist>
 736 <listitem>
 737 <para>
 738 If &cv-CPPDEFINES; is a string,
 739 the values of the
 740 &cv-link-CPPDEFPREFIX; and &cv-link-CPPDEFSUFFIX; &consvars;
 741 are respectively prepended and appended to
 742 each definition in &cv-CPPDEFINES;,
 743 split on whitespace.
 744 </para>
 745
 746 <example_commands>
 747 # Adds -Dxyz to POSIX compiler command lines,
 748 # and /Dxyz to Microsoft Visual C++ command lines.
 749 env = Environment(CPPDEFINES='xyz')
 750 </example_commands>
 751
 752 </listitem>
 753 <listitem>
 754 <para>
 755 If &cv-CPPDEFINES; is a list,
 756 the values of the
 757 &cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; &consvars;
 758 are respectively prepended and appended to
 759 each element in the list.
 760 If any element is a tuple (or list)
 761 then the first item of the tuple is the macro name
 762 and the second is the macro definition.
 763 If the definition is not omitted or <literal>None</literal>,
 764 the name and definition are combined into a single
 765 <literal>name=definition</literal> item
 766 before the preending/appending.
 767 </para>
 768
 769 <example_commands>
 770 # Adds -DB=2 -DA to POSIX compiler command lines,
 771 # and /DB=2 /DA to Microsoft Visual C++ command lines.
 772 env = Environment(CPPDEFINES=[('B', 2), 'A'])
 773 </example_commands>
 774
 775 </listitem>
 776 <listitem>
 777 <para>
 778 If &cv-CPPDEFINES; is a dictionary,
 779 the values of the
 780 &cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; &consvars;
 781 are respectively prepended and appended to
 782 each key from the dictionary.
 783 If the value for a key is not <literal>None</literal>,
 784 then the key (macro name) and the value
 785 (macros definition) are combined into a single
 786 <literal>name=definition</literal> item
 787 before the prepending/appending.
 788 </para>
 789
 790 <example_commands>
 791 # Adds -DA -DB=2 to POSIX compiler command lines,
 792 # or /DA /DB=2 to Microsoft Visual C++ command lines.
 793 env = Environment(CPPDEFINES={'B':2, 'A':None})
 794 </example_commands>
 795 </listitem>
 796 </itemizedlist>
 797
 798 <para>
 799 Depending on how contents are added to &cv-CPPDEFINES;,
 800 it may be transformed into a compound type,
 801 for example a list containing strings, tuples and/or dictionaries.
 802 &SCons; can correctly expand such a compound type.
 803 </para>
 804
 805 <para>
 806 Note that &SCons; may call the compiler via a shell.
 807 If a macro definition contains characters such as spaces that
 808 have meaning to the shell, or is intended to be a string value,
 809 you may need to use the shell's quoting syntax to avoid
 810 interpretation by the shell before the preprocessor sees it.
 811 Function-like macros are not supported via this mechanism
 812 (and some compilers do not even implement that functionality
 813 via the command lines).
 814 When quoting, note that
 815 one set of quote characters are used to define a &Python; string,
 816 then quotes embedded inside that would be consumed by the shell
 817 unless escaped.  These examples may help illustrate:
 818 </para>
 819
 820 <example_commands>
 821 env = Environment(CPPDEFINES=['USE_ALT_HEADER=\\"foo_alt.h\\"'])
 822 env = Environment(CPPDEFINES=[('USE_ALT_HEADER', '\\"foo_alt.h\\"')])
 823 </example_commands>
 824
 825 <para>
 826 :<emphasis>Changed in version  4.5</emphasis>:
 827 &SCons; no longer sorts &cv-CPPDEFINES; values entered
 828 in dictionary form.  &Python; now preserves dictionary
 829 keys in the order they are entered, so it is no longer
 830 necessary to sort them to ensure a stable command line.
 831 </para>
 832
 833 </listitem>
 834   </varlistentry>
 835   <varlistentry id="cv-CPPDEFPREFIX">
 836     <term>
 837       <envar>CPPDEFPREFIX</envar>
 838     </term>
 839     <listitem><para>
 840 The prefix used to specify preprocessor macro definitions
 841 on the C compiler command line.
 842 This will be prepended to each definition
 843 in the &cv-link-CPPDEFINES; &consvar;
 844 when the &cv-link-_CPPDEFFLAGS; variable is automatically generated.
 845 </para>
 846 </listitem>
 847   </varlistentry>
 848   <varlistentry id="cv-CPPDEFSUFFIX">
 849     <term>
 850       <envar>CPPDEFSUFFIX</envar>
 851     </term>
 852     <listitem><para>
 853 The suffix used to specify preprocessor macro definitions
 854 on the C compiler command line.
 855 This will be appended to each definition
 856 in the &cv-link-CPPDEFINES; &consvar;
 857 when the &cv-link-_CPPDEFFLAGS; variable is automatically generated.
 858 </para>
 859 </listitem>
 860   </varlistentry>
 861   <varlistentry id="cv-CPPFLAGS">
 862     <term>
 863       <envar>CPPFLAGS</envar>
 864     </term>
 865     <listitem><para>
 866 User-specified C preprocessor options.
 867 These will be included in any command that uses the C preprocessor,
 868 including not just compilation of C and C++ source files
 869 via the &cv-link-CCCOM;,
 870 &cv-link-SHCCCOM;,
 871 &cv-link-CXXCOM; and
 872 &cv-link-SHCXXCOM; command lines,
 873 but also the &cv-link-FORTRANPPCOM;,
 874 &cv-link-SHFORTRANPPCOM;,
 875 &cv-link-F77PPCOM; and
 876 &cv-link-SHF77PPCOM; command lines
 877 used to compile a Fortran source file,
 878 and the &cv-link-ASPPCOM; command line
 879 used to assemble an assembly language source file,
 880 after first running each file through the C preprocessor.
 881 Note that this variable does
 882 <emphasis>not</emphasis>
 883 contain
 884 <option>-I</option>
 885 (or similar) include search path options
 886 that scons generates automatically from &cv-link-CPPPATH;.
 887 See &cv-link-_CPPINCFLAGS;, below,
 888 for the variable that expands to those options.
 889 </para>
 890 </listitem>
 891   </varlistentry>
 892   <varlistentry id="cv-_CPPINCFLAGS">
 893     <term>
 894       <envar>_CPPINCFLAGS</envar>
 895     </term>
 896     <listitem><para>
 897 An automatically-generated &consvar;
 898 containing the C preprocessor command-line options
 899 for specifying directories to be searched for include files.
 900 The value of &cv-_CPPINCFLAGS; is created
 901 by respectively prepending and appending
 902 &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
 903 to each directory in &cv-link-CPPPATH;.
 904 </para>
 905 </listitem>
 906   </varlistentry>
 907   <varlistentry id="cv-CPPPATH">
 908     <term>
 909       <envar>CPPPATH</envar>
 910     </term>
 911     <listitem><para>
 912 The list of directories that the C preprocessor will search for include
 913 directories. The C/C++ implicit dependency scanner will search these
 914 directories for include files.
 915 In general it's not advised to put include directory directives
 916 directly into &cv-link-CCFLAGS; or &cv-link-CXXFLAGS;
 917 as the result will be non-portable
 918 and the directories will not be searched by the dependency scanner.
 919 &cv-CPPPATH; should be a list of path strings,
 920 or a single string, not a pathname list joined by
 921 Python's <systemitem>os.pathsep</systemitem>.
 922 </para>
 923
 924 <para>
 925 Note:
 926 directory names in &cv-CPPPATH;
 927 will be looked-up relative to the directory of the SConscript file
 928 when they are used in a command.
 929 To force &scons;
 930 to look-up a directory relative to the root of the source tree use
 931 the <literal>#</literal> prefix:
 932 </para>
 933
 934 <example_commands>
 935 env = Environment(CPPPATH='#/include')
 936 </example_commands>
 937
 938 <para>
 939 The directory look-up can also be forced using the
 940 &f-link-Dir;
 941 function:
 942 </para>
 943
 944 <example_commands>
 945 include = Dir('include')
 946 env = Environment(CPPPATH=include)
 947 </example_commands>
 948
 949 <para>
 950 The directory list will be added to command lines
 951 through the automatically-generated
 952 &cv-link-_CPPINCFLAGS; &consvar;,
 953 which is constructed by
 954 respectively prepending and appending the values of the
 955 &cv-link-INCPREFIX; and &cv-link-INCSUFFIX; &consvars;
 956 to each directory in &cv-link-CPPPATH;.
 957 Any command lines you define that need
 958 the &cv-CPPPATH; directory list should
 959 include &cv-link-_CPPINCFLAGS;:
 960 </para>
 961
 962 <example_commands>
 963 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
 964 </example_commands>
 965 </listitem>
 966   </varlistentry>
 967   <varlistentry id="cv-CPPSUFFIXES">
 968     <term>
 969       <envar>CPPSUFFIXES</envar>
 970     </term>
 971     <listitem><para>
 972 The list of suffixes of files that will be scanned
 973 for C preprocessor implicit dependencies
 974 (#include lines).
 975 The default list is:
 976 </para>
 977
 978 <example_commands>
 979 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
 980  ".h", ".H", ".hxx", ".hpp", ".hh",
 981  ".F", ".fpp", ".FPP",
 982  ".m", ".mm",
 983  ".S", ".spp", ".SPP"]
 984 </example_commands>
 985 </listitem>
 986   </varlistentry>
 987   <varlistentry id="cv-CXX">
 988     <term>
 989       <envar>CXX</envar>
 990     </term>
 991     <listitem><para>
 992 The C++ compiler.
 993 See also &cv-link-SHCXX; for compiling to shared objects..
 994 </para>
 995 </listitem>
 996   </varlistentry>
 997   <varlistentry id="cv-CXXCOM">
 998     <term>
 999       <envar>CXXCOM</envar>
1000     </term>
1001     <listitem><para>
1002 The command line used to compile a C++ source file to an object file.
1003 Any options specified in the &cv-link-CXXFLAGS; and
1004 &cv-link-CPPFLAGS; construction variables
1005 are included on this command line.
1006 See also &cv-link-SHCXXCOM; for compiling to shared objects..
1007 </para>
1008 </listitem>
1009   </varlistentry>
1010   <varlistentry id="cv-CXXCOMSTR">
1011     <term>
1012       <envar>CXXCOMSTR</envar>
1013     </term>
1014     <listitem><para>
1015 If set, the string displayed when a C++ source file
1016 is compiled to a (static) object file.
1017 If not set, then &cv-link-CXXCOM; (the command line) is displayed.
1018 See also &cv-link-SHCXXCOMSTR; for compiling to shared objects..
1019 </para>
1020
1021 <example_commands>
1022 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
1023 </example_commands>
1024 </listitem>
1025   </varlistentry>
1026   <varlistentry id="cv-CXXFILESUFFIX">
1027     <term>
1028       <envar>CXXFILESUFFIX</envar>
1029     </term>
1030     <listitem><para>
1031 The suffix for C++ source files.
1032 This is used by the internal CXXFile builder
1033 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
1034 The default suffix is
1035 <filename>.cc</filename>.
1036 SCons also treats files with the suffixes
1037 <filename>.cpp</filename>,
1038 <filename>.cxx</filename>,
1039 <filename>.c++</filename>,
1040 and
1041 <filename>.C++</filename>
1042 as C++ files,
1043 and files with
1044 <filename>.mm</filename>
1045 suffixes as Objective C++ files.
1046 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
1047 SCons also treats
1048 <filename>.C</filename>
1049 (upper case) files
1050 as C++ files.
1051 </para>
1052 </listitem>
1053   </varlistentry>
1054   <varlistentry id="cv-CXXFLAGS">
1055     <term>
1056       <envar>CXXFLAGS</envar>
1057     </term>
1058     <listitem><para>
1059 General options that are passed to the C++ compiler.
1060 By default, this includes the value of &cv-link-CCFLAGS;,
1061 so that setting &cv-CCFLAGS; affects both C and C++ compilation.
1062 If you want to add C++-specific flags,
1063 you must set or override the value of &cv-link-CXXFLAGS;.
1064 See also &cv-link-SHCXXFLAGS; for compiling to shared objects..
1065 </para>
1066 </listitem>
1067   </varlistentry>
1068   <varlistentry id="cv-CXXVERSION">
1069     <term>
1070       <envar>CXXVERSION</envar>
1071     </term>
1072     <listitem><para>
1073 The version number of the C++ compiler.
1074 This may or may not be set,
1075 depending on the specific C++ compiler being used.
1076 </para>
1077 </listitem>
1078   </varlistentry>
1079   <varlistentry id="cv-DC">
1080     <term>
1081       <envar>DC</envar>
1082     </term>
1083     <listitem><para>
1084 The D compiler to use.
1085 See also &cv-link-SHDC; for compiling to shared objects.
1086 </para>
1087 </listitem>
1088   </varlistentry>
1089   <varlistentry id="cv-DCOM">
1090     <term>
1091       <envar>DCOM</envar>
1092     </term>
1093     <listitem><para>
1094 The command line used to compile a D file to an object file.
1095 Any options specified in the &cv-link-DFLAGS; construction variable
1096 is included on this command line.
1097 See also &cv-link-SHDCOM; for compiling to shared objects.
1098 </para>
1099 </listitem>
1100   </varlistentry>
1101   <varlistentry id="cv-DCOMSTR">
1102     <term>
1103       <envar>DCOMSTR</envar>
1104     </term>
1105     <listitem><para>
1106 If set, the string displayed when a D source file
1107 is compiled to a (static) object file.
1108 If not set, then &cv-link-DCOM; (the command line) is displayed.
1109 See also &cv-link-SHDCOMSTR; for compiling to shared objects.
1110 </para>
1111 </listitem>
1112   </varlistentry>
1113   <varlistentry id="cv-DDEBUG">
1114     <term>
1115       <envar>DDEBUG</envar>
1116     </term>
1117     <listitem><para>
1118 List of debug tags to enable when compiling.
1119 </para>
1120 </listitem>
1121   </varlistentry>
1122   <varlistentry id="cv-DDEBUGPREFIX">
1123     <term>
1124       <envar>DDEBUGPREFIX</envar>
1125     </term>
1126     <listitem><para>
1127 DDEBUGPREFIX.
1128 </para>
1129 </listitem>
1130   </varlistentry>
1131   <varlistentry id="cv-DDEBUGSUFFIX">
1132     <term>
1133       <envar>DDEBUGSUFFIX</envar>
1134     </term>
1135     <listitem><para>
1136 DDEBUGSUFFIX.
1137 </para>
1138 </listitem>
1139   </varlistentry>
1140   <varlistentry id="cv-DESCRIPTION">
1141     <term>
1142       <envar>DESCRIPTION</envar>
1143     </term>
1144     <listitem><para>
1145 A long description of the project being packaged.
1146 This is included in the relevant section
1147 of the file that controls the packaging build.
1148 </para>
1149 <para>See the &b-link-Package; builder.</para>
1150 </listitem>
1151   </varlistentry>
1152   <varlistentry id="cv-DESCRIPTION_lang">
1153     <term>
1154       <envar>DESCRIPTION_lang</envar>
1155     </term>
1156     <listitem><para>
1157 A language-specific long description for
1158 the specified <varname>lang</varname>.
1159 This is used to populate a
1160 <literal>%description -l</literal>
1161 section of an RPM
1162 <filename>.spec</filename> file.
1163 </para>
1164 <para>See the &b-link-Package; builder.</para>
1165 </listitem>
1166   </varlistentry>
1167   <varlistentry id="cv-DFILESUFFIX">
1168     <term>
1169       <envar>DFILESUFFIX</envar>
1170     </term>
1171     <listitem><para>
1172 DFILESUFFIX.
1173 </para>
1174 </listitem>
1175   </varlistentry>
1176   <varlistentry id="cv-DFLAGPREFIX">
1177     <term>
1178       <envar>DFLAGPREFIX</envar>
1179     </term>
1180     <listitem><para>
1181 DFLAGPREFIX.
1182 </para>
1183 </listitem>
1184   </varlistentry>
1185   <varlistentry id="cv-DFLAGS">
1186     <term>
1187       <envar>DFLAGS</envar>
1188     </term>
1189     <listitem><para>
1190 General options that are passed to the D compiler.
1191 </para>
1192 </listitem>
1193   </varlistentry>
1194   <varlistentry id="cv-DFLAGSUFFIX">
1195     <term>
1196       <envar>DFLAGSUFFIX</envar>
1197     </term>
1198     <listitem><para>
1199 DFLAGSUFFIX.
1200 </para>
1201 </listitem>
1202   </varlistentry>
1203   <varlistentry id="cv-DI_FILE_DIR">
1204     <term>
1205       <envar>DI_FILE_DIR</envar>
1206     </term>
1207     <listitem><para>
1208 Path where .di files will be generated
1209 </para>
1210 </listitem>
1211   </varlistentry>
1212   <varlistentry id="cv-DI_FILE_DIR_PREFIX">
1213     <term>
1214       <envar>DI_FILE_DIR_PREFIX</envar>
1215     </term>
1216     <listitem><para>
1217 Prefix to send the di path argument to compiler
1218 </para>
1219 </listitem>
1220   </varlistentry>
1221   <varlistentry id="cv-DI_FILE_DIR_SUFFFIX">
1222     <term>
1223       <envar>DI_FILE_DIR_SUFFFIX</envar>
1224     </term>
1225     <listitem><para>
1226 Suffix to send the di path argument to compiler
1227 </para>
1228 </listitem>
1229   </varlistentry>
1230   <varlistentry id="cv-DI_FILE_SUFFIX">
1231     <term>
1232       <envar>DI_FILE_SUFFIX</envar>
1233     </term>
1234     <listitem><para>
1235 Suffix of d include files default is .di
1236 </para>
1237 </listitem>
1238   </varlistentry>
1239   <varlistentry id="cv-DINCPREFIX">
1240     <term>
1241       <envar>DINCPREFIX</envar>
1242     </term>
1243     <listitem><para>
1244 DINCPREFIX.
1245 </para>
1246 </listitem>
1247   </varlistentry>
1248   <varlistentry id="cv-DINCSUFFIX">
1249     <term>
1250       <envar>DINCSUFFIX</envar>
1251     </term>
1252     <listitem><para>
1253 DLIBFLAGSUFFIX.
1254 </para>
1255 </listitem>
1256   </varlistentry>
1257   <varlistentry id="cv-Dir">
1258     <term>
1259       <envar>Dir</envar>
1260     </term>
1261     <listitem><para>
1262 A function that converts a string
1263 into a Dir instance relative to the target being built.
1264 </para>
1265 </listitem>
1266   </varlistentry>
1267   <varlistentry id="cv-Dirs">
1268     <term>
1269       <envar>Dirs</envar>
1270     </term>
1271     <listitem><para>
1272 A function that converts a list of strings
1273 into a list of Dir instances relative to the target being built.
1274 </para>
1275 </listitem>
1276   </varlistentry>
1277   <varlistentry id="cv-DLIB">
1278     <term>
1279       <envar>DLIB</envar>
1280     </term>
1281     <listitem><para>
1282 Name of the lib tool to use for D codes.
1283 </para>
1284 </listitem>
1285   </varlistentry>
1286   <varlistentry id="cv-DLIBCOM">
1287     <term>
1288       <envar>DLIBCOM</envar>
1289     </term>
1290     <listitem><para>
1291 The command line to use when creating libraries.
1292 </para>
1293 </listitem>
1294   </varlistentry>
1295   <varlistentry id="cv-DLIBDIRPREFIX">
1296     <term>
1297       <envar>DLIBDIRPREFIX</envar>
1298     </term>
1299     <listitem><para>
1300 DLIBLINKPREFIX.
1301 </para>
1302 </listitem>
1303   </varlistentry>
1304   <varlistentry id="cv-DLIBDIRSUFFIX">
1305     <term>
1306       <envar>DLIBDIRSUFFIX</envar>
1307     </term>
1308     <listitem><para>
1309 DLIBLINKSUFFIX.
1310 </para>
1311 </listitem>
1312   </varlistentry>
1313   <varlistentry id="cv-DLIBFLAGPREFIX">
1314     <term>
1315       <envar>DLIBFLAGPREFIX</envar>
1316     </term>
1317     <listitem><para>
1318 DLIBFLAGPREFIX.
1319 </para>
1320 </listitem>
1321   </varlistentry>
1322   <varlistentry id="cv-DLIBFLAGSUFFIX">
1323     <term>
1324       <envar>DLIBFLAGSUFFIX</envar>
1325     </term>
1326     <listitem><para>
1327 DLIBFLAGSUFFIX.
1328 </para>
1329 </listitem>
1330   </varlistentry>
1331   <varlistentry id="cv-DLIBLINKPREFIX">
1332     <term>
1333       <envar>DLIBLINKPREFIX</envar>
1334     </term>
1335     <listitem><para>
1336 DLIBLINKPREFIX.
1337 </para>
1338 </listitem>
1339   </varlistentry>
1340   <varlistentry id="cv-DLIBLINKSUFFIX">
1341     <term>
1342       <envar>DLIBLINKSUFFIX</envar>
1343     </term>
1344     <listitem><para>
1345 DLIBLINKSUFFIX.
1346 </para>
1347 </listitem>
1348   </varlistentry>
1349   <varlistentry id="cv-DLINK">
1350     <term>
1351       <envar>DLINK</envar>
1352     </term>
1353     <listitem><para>
1354 Name of the linker to use for linking systems including D sources.
1355 See also &cv-link-SHDLINK; for linking shared objects.
1356 </para>
1357 </listitem>
1358   </varlistentry>
1359   <varlistentry id="cv-DLINKCOM">
1360     <term>
1361       <envar>DLINKCOM</envar>
1362     </term>
1363     <listitem><para>
1364 The command line to use when linking systems including D sources.
1365 See also &cv-link-SHDLINKCOM; for linking shared objects.
1366 </para>
1367 </listitem>
1368   </varlistentry>
1369   <varlistentry id="cv-DLINKFLAGPREFIX">
1370     <term>
1371       <envar>DLINKFLAGPREFIX</envar>
1372     </term>
1373     <listitem><para>
1374 DLINKFLAGPREFIX.
1375 </para>
1376 </listitem>
1377   </varlistentry>
1378   <varlistentry id="cv-DLINKFLAGS">
1379     <term>
1380       <envar>DLINKFLAGS</envar>
1381     </term>
1382     <listitem><para>
1383 List of linker flags.
1384 See also &cv-link-SHDLINKFLAGS; for linking shared objects.
1385 </para>
1386 </listitem>
1387   </varlistentry>
1388   <varlistentry id="cv-DLINKFLAGSUFFIX">
1389     <term>
1390       <envar>DLINKFLAGSUFFIX</envar>
1391     </term>
1392     <listitem><para>
1393 DLINKFLAGSUFFIX.
1394 </para>
1395 </listitem>
1396   </varlistentry>
1397   <varlistentry id="cv-DOCBOOK_DEFAULT_XSL_EPUB">
1398     <term>
1399       <envar>DOCBOOK_DEFAULT_XSL_EPUB</envar>
1400     </term>
1401     <listitem><para>
1402 The default XSLT file for the &b-link-DocbookEpub; builder within the
1403 current environment, if no other XSLT gets specified via keyword.
1404 </para>
1405 </listitem>
1406   </varlistentry>
1407   <varlistentry id="cv-DOCBOOK_DEFAULT_XSL_HTML">
1408     <term>
1409       <envar>DOCBOOK_DEFAULT_XSL_HTML</envar>
1410     </term>
1411     <listitem><para>
1412 The default XSLT file for the &b-link-DocbookHtml; builder within the
1413 current environment, if no other XSLT gets specified via keyword.
1414 </para>
1415 </listitem>
1416   </varlistentry>
1417   <varlistentry id="cv-DOCBOOK_DEFAULT_XSL_HTMLCHUNKED">
1418     <term>
1419       <envar>DOCBOOK_DEFAULT_XSL_HTMLCHUNKED</envar>
1420     </term>
1421     <listitem><para>
1422 The default XSLT file for the &b-link-DocbookHtmlChunked; builder within the
1423 current environment, if no other XSLT gets specified via keyword.
1424 </para>
1425 </listitem>
1426   </varlistentry>
1427   <varlistentry id="cv-DOCBOOK_DEFAULT_XSL_HTMLHELP">
1428     <term>
1429       <envar>DOCBOOK_DEFAULT_XSL_HTMLHELP</envar>
1430     </term>
1431     <listitem><para>
1432 The default XSLT file for the &b-link-DocbookHtmlhelp; builder within the
1433 current environment, if no other XSLT gets specified via keyword.
1434 </para>
1435 </listitem>
1436   </varlistentry>
1437   <varlistentry id="cv-DOCBOOK_DEFAULT_XSL_MAN">
1438     <term>
1439       <envar>DOCBOOK_DEFAULT_XSL_MAN</envar>
1440     </term>
1441     <listitem><para>
1442 The default XSLT file for the &b-link-DocbookMan; builder within the
1443 current environment, if no other XSLT gets specified via keyword.
1444 </para>
1445 </listitem>
1446   </varlistentry>
1447   <varlistentry id="cv-DOCBOOK_DEFAULT_XSL_PDF">
1448     <term>
1449       <envar>DOCBOOK_DEFAULT_XSL_PDF</envar>
1450     </term>
1451     <listitem><para>
1452 The default XSLT file for the &b-link-DocbookPdf; builder within the
1453 current environment, if no other XSLT gets specified via keyword.
1454 </para>
1455 </listitem>
1456   </varlistentry>
1457   <varlistentry id="cv-DOCBOOK_DEFAULT_XSL_SLIDESHTML">
1458     <term>
1459       <envar>DOCBOOK_DEFAULT_XSL_SLIDESHTML</envar>
1460     </term>
1461     <listitem><para>
1462 The default XSLT file for the &b-link-DocbookSlidesHtml; builder within the
1463 current environment, if no other XSLT gets specified via keyword.
1464 </para>
1465 </listitem>
1466   </varlistentry>
1467   <varlistentry id="cv-DOCBOOK_DEFAULT_XSL_SLIDESPDF">
1468     <term>
1469       <envar>DOCBOOK_DEFAULT_XSL_SLIDESPDF</envar>
1470     </term>
1471     <listitem><para>
1472 The default XSLT file for the &b-link-DocbookSlidesPdf; builder within the
1473 current environment, if no other XSLT gets specified via keyword.
1474 </para>
1475 </listitem>
1476   </varlistentry>
1477   <varlistentry id="cv-DOCBOOK_FOP">
1478     <term>
1479       <envar>DOCBOOK_FOP</envar>
1480     </term>
1481     <listitem><para>
1482 The path to the PDF renderer <literal>fop</literal> or <literal>xep</literal>,
1483 if one of them is installed (<literal>fop</literal> gets checked first).
1484 </para>
1485 </listitem>
1486   </varlistentry>
1487   <varlistentry id="cv-DOCBOOK_FOPCOM">
1488     <term>
1489       <envar>DOCBOOK_FOPCOM</envar>
1490     </term>
1491     <listitem><para>
1492 The full command-line for the
1493 PDF renderer <literal>fop</literal> or <literal>xep</literal>.
1494 </para>
1495 </listitem>
1496   </varlistentry>
1497   <varlistentry id="cv-DOCBOOK_FOPCOMSTR">
1498     <term>
1499       <envar>DOCBOOK_FOPCOMSTR</envar>
1500     </term>
1501     <listitem><para>
1502 The string displayed when a renderer like <literal>fop</literal> or
1503 <literal>xep</literal> is used to create PDF output from an XML file.
1504 </para>
1505 </listitem>
1506   </varlistentry>
1507   <varlistentry id="cv-DOCBOOK_FOPFLAGS">
1508     <term>
1509       <envar>DOCBOOK_FOPFLAGS</envar>
1510     </term>
1511     <listitem><para>
1512 Additonal command-line flags for the
1513 PDF renderer <literal>fop</literal> or <literal>xep</literal>.
1514 </para>
1515 </listitem>
1516   </varlistentry>
1517   <varlistentry id="cv-DOCBOOK_XMLLINT">
1518     <term>
1519       <envar>DOCBOOK_XMLLINT</envar>
1520     </term>
1521     <listitem><para>
1522 The path to the external executable <literal>xmllint</literal>, if it's installed.
1523 Note, that this is only used as last fallback for resolving
1524 XIncludes, if no lxml Python binding can be imported
1525 in the current system.
1526 </para>
1527 </listitem>
1528   </varlistentry>
1529   <varlistentry id="cv-DOCBOOK_XMLLINTCOM">
1530     <term>
1531       <envar>DOCBOOK_XMLLINTCOM</envar>
1532     </term>
1533     <listitem><para>
1534 The full command-line for the external executable
1535 <literal>xmllint</literal>.
1536 </para>
1537 </listitem>
1538   </varlistentry>
1539   <varlistentry id="cv-DOCBOOK_XMLLINTCOMSTR">
1540     <term>
1541       <envar>DOCBOOK_XMLLINTCOMSTR</envar>
1542     </term>
1543     <listitem><para>
1544 The string displayed when <literal>xmllint</literal> is used to resolve
1545 XIncludes for a given XML file.
1546 </para>
1547 </listitem>
1548   </varlistentry>
1549   <varlistentry id="cv-DOCBOOK_XMLLINTFLAGS">
1550     <term>
1551       <envar>DOCBOOK_XMLLINTFLAGS</envar>
1552     </term>
1553     <listitem><para>
1554 Additonal command-line flags for the external executable
1555 <literal>xmllint</literal>.
1556 </para>
1557 </listitem>
1558   </varlistentry>
1559   <varlistentry id="cv-DOCBOOK_XSLTPROC">
1560     <term>
1561       <envar>DOCBOOK_XSLTPROC</envar>
1562     </term>
1563     <listitem><para>
1564 The path to the external executable <literal>xsltproc</literal>
1565 (or <literal>saxon</literal>, <literal>xalan</literal>), if one of them
1566 is installed.
1567 Note, that this is only used as last fallback for XSL transformations, if
1568 no lxml Python binding can be imported in the current system.
1569 </para>
1570 </listitem>
1571   </varlistentry>
1572   <varlistentry id="cv-DOCBOOK_XSLTPROCCOM">
1573     <term>
1574       <envar>DOCBOOK_XSLTPROCCOM</envar>
1575     </term>
1576     <listitem><para>
1577 The full command-line for the external executable
1578 <literal>xsltproc</literal> (or <literal>saxon</literal>,
1579 <literal>xalan</literal>).
1580 </para>
1581 </listitem>
1582   </varlistentry>
1583   <varlistentry id="cv-DOCBOOK_XSLTPROCCOMSTR">
1584     <term>
1585       <envar>DOCBOOK_XSLTPROCCOMSTR</envar>
1586     </term>
1587     <listitem><para>
1588 The string displayed when <literal>xsltproc</literal> is used to transform
1589 an XML file via a given XSLT stylesheet.
1590 </para>
1591 </listitem>
1592   </varlistentry>
1593   <varlistentry id="cv-DOCBOOK_XSLTPROCFLAGS">
1594     <term>
1595       <envar>DOCBOOK_XSLTPROCFLAGS</envar>
1596     </term>
1597     <listitem><para>
1598 Additonal command-line flags for the external executable
1599 <literal>xsltproc</literal> (or <literal>saxon</literal>,
1600 <literal>xalan</literal>).
1601 </para>
1602 </listitem>
1603   </varlistentry>
1604   <varlistentry id="cv-DOCBOOK_XSLTPROCPARAMS">
1605     <term>
1606       <envar>DOCBOOK_XSLTPROCPARAMS</envar>
1607     </term>
1608     <listitem><para>
1609 Additonal parameters that are not intended for the XSLT processor executable, but
1610 the XSL processing itself. By default, they get appended at the end of the command line
1611 for <literal>saxon</literal> and <literal>saxon-xslt</literal>, respectively.
1612 </para>
1613 </listitem>
1614   </varlistentry>
1615   <varlistentry id="cv-DPATH">
1616     <term>
1617       <envar>DPATH</envar>
1618     </term>
1619     <listitem><para>
1620   List of paths to search for import modules.
1621 </para>
1622 </listitem>
1623   </varlistentry>
1624   <varlistentry id="cv-DRPATHPREFIX">
1625     <term>
1626       <envar>DRPATHPREFIX</envar>
1627     </term>
1628     <listitem><para>
1629 DRPATHPREFIX.
1630 </para>
1631 </listitem>
1632   </varlistentry>
1633   <varlistentry id="cv-DRPATHSUFFIX">
1634     <term>
1635       <envar>DRPATHSUFFIX</envar>
1636     </term>
1637     <listitem><para>
1638 DRPATHSUFFIX.
1639 </para>
1640 </listitem>
1641   </varlistentry>
1642   <varlistentry id="cv-DSUFFIXES">
1643     <term>
1644       <envar>DSUFFIXES</envar>
1645     </term>
1646     <listitem><para>
1647 The list of suffixes of files that will be scanned
1648 for imported D package files.
1649 The default list is <literal>['.d']</literal>.
1650 </para>
1651 </listitem>
1652   </varlistentry>
1653   <varlistentry id="cv-DVERPREFIX">
1654     <term>
1655       <envar>DVERPREFIX</envar>
1656     </term>
1657     <listitem><para>
1658 DVERPREFIX.
1659 </para>
1660 </listitem>
1661   </varlistentry>
1662   <varlistentry id="cv-DVERSIONS">
1663     <term>
1664       <envar>DVERSIONS</envar>
1665     </term>
1666     <listitem><para>
1667 List of version tags to enable when compiling.
1668 </para>
1669 </listitem>
1670   </varlistentry>
1671   <varlistentry id="cv-DVERSUFFIX">
1672     <term>
1673       <envar>DVERSUFFIX</envar>
1674     </term>
1675     <listitem><para>
1676 DVERSUFFIX.
1677 </para>
1678 </listitem>
1679   </varlistentry>
1680   <varlistentry id="cv-DVIPDF">
1681     <term>
1682       <envar>DVIPDF</envar>
1683     </term>
1684     <listitem><para>
1685 The TeX DVI file to PDF file converter.
1686 </para>
1687 </listitem>
1688   </varlistentry>
1689   <varlistentry id="cv-DVIPDFCOM">
1690     <term>
1691       <envar>DVIPDFCOM</envar>
1692     </term>
1693     <listitem><para>
1694 The command line used to convert TeX DVI files into a PDF file.
1695 </para>
1696 </listitem>
1697   </varlistentry>
1698   <varlistentry id="cv-DVIPDFCOMSTR">
1699     <term>
1700       <envar>DVIPDFCOMSTR</envar>
1701     </term>
1702     <listitem><para>
1703 The string displayed when a TeX DVI file
1704 is converted into a PDF file.
1705 If this is not set, then &cv-link-DVIPDFCOM; (the command line) is displayed.
1706 </para>
1707 </listitem>
1708   </varlistentry>
1709   <varlistentry id="cv-DVIPDFFLAGS">
1710     <term>
1711       <envar>DVIPDFFLAGS</envar>
1712     </term>
1713     <listitem><para>
1714 General options passed to the TeX DVI file to PDF file converter.
1715 </para>
1716 </listitem>
1717   </varlistentry>
1718   <varlistentry id="cv-DVIPS">
1719     <term>
1720       <envar>DVIPS</envar>
1721     </term>
1722     <listitem><para>
1723 The TeX DVI file to PostScript converter.
1724 </para>
1725 </listitem>
1726   </varlistentry>
1727   <varlistentry id="cv-DVIPSFLAGS">
1728     <term>
1729       <envar>DVIPSFLAGS</envar>
1730     </term>
1731     <listitem><para>
1732 General options passed to the TeX DVI file to PostScript converter.
1733 </para>
1734 </listitem>
1735   </varlistentry>
1736   <varlistentry id="cv-ENV">
1737     <term>
1738       <envar>ENV</envar>
1739     </term>
1740     <listitem><para>
1741 The <firstterm>execution environment</firstterm> -
1742 a dictionary of environment variables
1743 used when &SCons; invokes external commands
1744 to build targets defined in this &consenv;.
1745 When &cv-ENV; is passed to a command,
1746 all list values are assumed to be path lists and
1747 are joined using the search path separator.
1748 Any other non-string values are coerced to a string.
1749 </para>
1750
1751 <para>
1752 Note that by default
1753 &SCons;
1754 does
1755 <emphasis>not</emphasis>
1756 propagate the environment in effect when you execute
1757 &scons; (the "shell environment")
1758 to the execution environment.
1759 This is so that builds will be guaranteed
1760 repeatable regardless of the environment
1761 variables set at the time
1762 &scons;
1763 is invoked.
1764 If you want to propagate a
1765 shell environment variable
1766 to the commands executed
1767 to build target files,
1768 you must do so explicitly.
1769 A common example is
1770 the system &PATH;
1771 environment variable,
1772 so that
1773 &scons;
1774 will find utilities the same way
1775 as the invoking shell (or other process):
1776 </para>
1777
1778 <example_commands>
1779 import os
1780 env = Environment(ENV={'PATH': os.environ['PATH']})
1781 </example_commands>
1782
1783 <para>
1784 Although it is usually not recommended,
1785 you can propagate the entire shell environment
1786 in one go:
1787 </para>
1788
1789 <example_commands>
1790 import os
1791 env = Environment(ENV=os.environ.copy())
1792 </example_commands>
1793
1794 </listitem>
1795   </varlistentry>
1796   <varlistentry id="cv-ESCAPE">
1797     <term>
1798       <envar>ESCAPE</envar>
1799     </term>
1800     <listitem><para>
1801 A function that will be called to escape shell special characters in
1802 command lines. The function should take one argument: the command line
1803 string to escape; and should return the escaped command line.
1804 </para>
1805 </listitem>
1806   </varlistentry>
1807   <varlistentry id="cv-F03">
1808     <term>
1809       <envar>F03</envar>
1810     </term>
1811     <listitem><para>
1812 The Fortran 03 compiler.
1813 You should normally set the &cv-link-FORTRAN; variable,
1814 which specifies the default Fortran compiler
1815 for all Fortran versions.
1816 You only need to set &cv-link-F03; if you need to use a specific compiler
1817 or compiler version for Fortran 03 files.
1818 </para>
1819 </listitem>
1820   </varlistentry>
1821   <varlistentry id="cv-F03COM">
1822     <term>
1823       <envar>F03COM</envar>
1824     </term>
1825     <listitem><para>
1826 The command line used to compile a Fortran 03 source file to an object file.
1827 You only need to set &cv-link-F03COM; if you need to use a specific
1828 command line for Fortran 03 files.
1829 You should normally set the &cv-link-FORTRANCOM; variable,
1830 which specifies the default command line
1831 for all Fortran versions.
1832 </para>
1833 </listitem>
1834   </varlistentry>
1835   <varlistentry id="cv-F03COMSTR">
1836     <term>
1837       <envar>F03COMSTR</envar>
1838     </term>
1839     <listitem><para>
1840 If set, the string displayed when a Fortran 03 source file
1841 is compiled to an object file.
1842 If not set, then &cv-link-F03COM; or &cv-link-FORTRANCOM;
1843 (the command line) is displayed.
1844 </para>
1845 </listitem>
1846   </varlistentry>
1847   <varlistentry id="cv-F03FILESUFFIXES">
1848     <term>
1849       <envar>F03FILESUFFIXES</envar>
1850     </term>
1851     <listitem><para>
1852 The list of file extensions for which the F03 dialect will be used. By
1853 default, this is <literal>['.f03']</literal>
1854 </para>
1855 </listitem>
1856   </varlistentry>
1857   <varlistentry id="cv-F03FLAGS">
1858     <term>
1859       <envar>F03FLAGS</envar>
1860     </term>
1861     <listitem><para>
1862 General user-specified options that are passed to the Fortran 03 compiler.
1863 Note that this variable does
1864 <emphasis>not</emphasis>
1865 contain
1866 <option>-I</option>
1867 (or similar) include search path options
1868 that scons generates automatically from &cv-link-F03PATH;.
1869 See
1870 &cv-link-_F03INCFLAGS;
1871 below,
1872 for the variable that expands to those options.
1873 You only need to set &cv-link-F03FLAGS; if you need to define specific
1874 user options for Fortran 03 files.
1875 You should normally set the &cv-link-FORTRANFLAGS; variable,
1876 which specifies the user-specified options
1877 passed to the default Fortran compiler
1878 for all Fortran versions.
1879 </para>
1880 </listitem>
1881   </varlistentry>
1882   <varlistentry id="cv-_F03INCFLAGS">
1883     <term>
1884       <envar>_F03INCFLAGS</envar>
1885     </term>
1886     <listitem><para>
1887 An automatically-generated construction variable
1888 containing the Fortran 03 compiler command-line options
1889 for specifying directories to be searched for include files.
1890 The value of &cv-link-_F03INCFLAGS; is created
1891 by appending &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
1892 to the beginning and end
1893 of each directory in &cv-link-F03PATH;.
1894 </para>
1895 </listitem>
1896   </varlistentry>
1897   <varlistentry id="cv-F03PATH">
1898     <term>
1899       <envar>F03PATH</envar>
1900     </term>
1901     <listitem><para>
1902 The list of directories that the Fortran 03 compiler will search for include
1903 directories. The implicit dependency scanner will search these
1904 directories for include files. Don't explicitly put include directory
1905 arguments in &cv-link-F03FLAGS; because the result will be non-portable
1906 and the directories will not be searched by the dependency scanner. Note:
1907 directory names in &cv-link-F03PATH; will be looked-up relative to the SConscript
1908 directory when they are used in a command. To force
1909 &scons;
1910 to look-up a directory relative to the root of the source tree use #:
1911 You only need to set &cv-link-F03PATH; if you need to define a specific
1912 include path for Fortran 03 files.
1913 You should normally set the &cv-link-FORTRANPATH; variable,
1914 which specifies the include path
1915 for the default Fortran compiler
1916 for all Fortran versions.
1917 </para>
1918
1919 <example_commands>
1920 env = Environment(F03PATH='#/include')
1921 </example_commands>
1922
1923 <para>
1924 The directory look-up can also be forced using the
1925 &Dir;()
1926 function:
1927 </para>
1928
1929 <example_commands>
1930 include = Dir('include')
1931 env = Environment(F03PATH=include)
1932 </example_commands>
1933
1934 <para>
1935 The directory list will be added to command lines
1936 through the automatically-generated
1937 &cv-link-_F03INCFLAGS;
1938 construction variable,
1939 which is constructed by
1940 appending the values of the
1941 &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
1942 construction variables
1943 to the beginning and end
1944 of each directory in &cv-link-F03PATH;.
1945 Any command lines you define that need
1946 the F03PATH directory list should
1947 include &cv-link-_F03INCFLAGS;:
1948 </para>
1949
1950 <example_commands>
1951 env = Environment(F03COM="my_compiler $_F03INCFLAGS -c -o $TARGET $SOURCE")
1952 </example_commands>
1953 </listitem>
1954   </varlistentry>
1955   <varlistentry id="cv-F03PPCOM">
1956     <term>
1957       <envar>F03PPCOM</envar>
1958     </term>
1959     <listitem><para>
1960 The command line used to compile a Fortran 03 source file to an object file
1961 after first running the file through the C preprocessor.
1962 Any options specified in the &cv-link-F03FLAGS; and &cv-link-CPPFLAGS; construction variables
1963 are included on this command line.
1964 You only need to set &cv-link-F03PPCOM; if you need to use a specific
1965 C-preprocessor command line for Fortran 03 files.
1966 You should normally set the &cv-link-FORTRANPPCOM; variable,
1967 which specifies the default C-preprocessor command line
1968 for all Fortran versions.
1969 </para>
1970 </listitem>
1971   </varlistentry>
1972   <varlistentry id="cv-F03PPCOMSTR">
1973     <term>
1974       <envar>F03PPCOMSTR</envar>
1975     </term>
1976     <listitem><para>
1977 If set, the string displayed when a Fortran 03 source file
1978 is compiled to an object file
1979 after first running the file through the C preprocessor.
1980 If not set, then &cv-link-F03PPCOM; or &cv-link-FORTRANPPCOM;
1981 (the command line) is displayed.
1982 </para>
1983 </listitem>
1984   </varlistentry>
1985   <varlistentry id="cv-F03PPFILESUFFIXES">
1986     <term>
1987       <envar>F03PPFILESUFFIXES</envar>
1988     </term>
1989     <listitem><para>
1990 The list of file extensions for which the compilation + preprocessor pass for
1991 F03 dialect will be used. By default, this is empty.
1992 </para>
1993 </listitem>
1994   </varlistentry>
1995   <varlistentry id="cv-F08">
1996     <term>
1997       <envar>F08</envar>
1998     </term>
1999     <listitem><para>
2000 The Fortran 08 compiler.
2001 You should normally set the &cv-link-FORTRAN; variable,
2002 which specifies the default Fortran compiler
2003 for all Fortran versions.
2004 You only need to set &cv-link-F08; if you need to use a specific compiler
2005 or compiler version for Fortran 08 files.
2006 </para>
2007 </listitem>
2008   </varlistentry>
2009   <varlistentry id="cv-F08COM">
2010     <term>
2011       <envar>F08COM</envar>
2012     </term>
2013     <listitem><para>
2014 The command line used to compile a Fortran 08 source file to an object file.
2015 You only need to set &cv-link-F08COM; if you need to use a specific
2016 command line for Fortran 08 files.
2017 You should normally set the &cv-link-FORTRANCOM; variable,
2018 which specifies the default command line
2019 for all Fortran versions.
2020 </para>
2021 </listitem>
2022   </varlistentry>
2023   <varlistentry id="cv-F08COMSTR">
2024     <term>
2025       <envar>F08COMSTR</envar>
2026     </term>
2027     <listitem><para>
2028 If set, the string displayed when a Fortran 08 source file
2029 is compiled to an object file.
2030 If not set, then &cv-link-F08COM; or &cv-link-FORTRANCOM;
2031 (the command line) is displayed.
2032 </para>
2033 </listitem>
2034   </varlistentry>
2035   <varlistentry id="cv-F08FILESUFFIXES">
2036     <term>
2037       <envar>F08FILESUFFIXES</envar>
2038     </term>
2039     <listitem><para>
2040 The list of file extensions for which the F08 dialect will be used. By
2041 default, this is <literal>['.f08']</literal>
2042 </para>
2043 </listitem>
2044   </varlistentry>
2045   <varlistentry id="cv-F08FLAGS">
2046     <term>
2047       <envar>F08FLAGS</envar>
2048     </term>
2049     <listitem><para>
2050 General user-specified options that are passed to the Fortran 08 compiler.
2051 Note that this variable does
2052 <emphasis>not</emphasis>
2053 contain
2054 <option>-I</option>
2055 (or similar) include search path options
2056 that scons generates automatically from &cv-link-F08PATH;.
2057 See
2058 &cv-link-_F08INCFLAGS;
2059 below,
2060 for the variable that expands to those options.
2061 You only need to set &cv-link-F08FLAGS; if you need to define specific
2062 user options for Fortran 08 files.
2063 You should normally set the &cv-link-FORTRANFLAGS; variable,
2064 which specifies the user-specified options
2065 passed to the default Fortran compiler
2066 for all Fortran versions.
2067 </para>
2068 </listitem>
2069   </varlistentry>
2070   <varlistentry id="cv-_F08INCFLAGS">
2071     <term>
2072       <envar>_F08INCFLAGS</envar>
2073     </term>
2074     <listitem><para>
2075 An automatically-generated construction variable
2076 containing the Fortran 08 compiler command-line options
2077 for specifying directories to be searched for include files.
2078 The value of &cv-link-_F08INCFLAGS; is created
2079 by appending &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
2080 to the beginning and end
2081 of each directory in &cv-link-F08PATH;.
2082 </para>
2083 </listitem>
2084   </varlistentry>
2085   <varlistentry id="cv-F08PATH">
2086     <term>
2087       <envar>F08PATH</envar>
2088     </term>
2089     <listitem><para>
2090 The list of directories that the Fortran 08 compiler will search for include
2091 directories. The implicit dependency scanner will search these
2092 directories for include files. Don't explicitly put include directory
2093 arguments in &cv-link-F08FLAGS; because the result will be non-portable
2094 and the directories will not be searched by the dependency scanner. Note:
2095 directory names in &cv-link-F08PATH; will be looked-up relative to the SConscript
2096 directory when they are used in a command. To force
2097 &scons;
2098 to look-up a directory relative to the root of the source tree use #:
2099 You only need to set &cv-link-F08PATH; if you need to define a specific
2100 include path for Fortran 08 files.
2101 You should normally set the &cv-link-FORTRANPATH; variable,
2102 which specifies the include path
2103 for the default Fortran compiler
2104 for all Fortran versions.
2105 </para>
2106
2107 <example_commands>
2108 env = Environment(F08PATH='#/include')
2109 </example_commands>
2110
2111 <para>
2112 The directory look-up can also be forced using the
2113 &Dir;()
2114 function:
2115 </para>
2116
2117 <example_commands>
2118 include = Dir('include')
2119 env = Environment(F08PATH=include)
2120 </example_commands>
2121
2122 <para>
2123 The directory list will be added to command lines
2124 through the automatically-generated
2125 &cv-link-_F08INCFLAGS;
2126 construction variable,
2127 which is constructed by
2128 appending the values of the
2129 &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
2130 construction variables
2131 to the beginning and end
2132 of each directory in &cv-link-F08PATH;.
2133 Any command lines you define that need
2134 the F08PATH directory list should
2135 include &cv-link-_F08INCFLAGS;:
2136 </para>
2137
2138 <example_commands>
2139 env = Environment(F08COM="my_compiler $_F08INCFLAGS -c -o $TARGET $SOURCE")
2140 </example_commands>
2141 </listitem>
2142   </varlistentry>
2143   <varlistentry id="cv-F08PPCOM">
2144     <term>
2145       <envar>F08PPCOM</envar>
2146     </term>
2147     <listitem><para>
2148 The command line used to compile a Fortran 08 source file to an object file
2149 after first running the file through the C preprocessor.
2150 Any options specified in the &cv-link-F08FLAGS; and &cv-link-CPPFLAGS; construction variables
2151 are included on this command line.
2152 You only need to set &cv-link-F08PPCOM; if you need to use a specific
2153 C-preprocessor command line for Fortran 08 files.
2154 You should normally set the &cv-link-FORTRANPPCOM; variable,
2155 which specifies the default C-preprocessor command line
2156 for all Fortran versions.
2157 </para>
2158 </listitem>
2159   </varlistentry>
2160   <varlistentry id="cv-F08PPCOMSTR">
2161     <term>
2162       <envar>F08PPCOMSTR</envar>
2163     </term>
2164     <listitem><para>
2165 If set, the string displayed when a Fortran 08 source file
2166 is compiled to an object file
2167 after first running the file through the C preprocessor.
2168 If not set, then &cv-link-F08PPCOM; or &cv-link-FORTRANPPCOM;
2169 (the command line) is displayed.
2170 </para>
2171 </listitem>
2172   </varlistentry>
2173   <varlistentry id="cv-F08PPFILESUFFIXES">
2174     <term>
2175       <envar>F08PPFILESUFFIXES</envar>
2176     </term>
2177     <listitem><para>
2178 The list of file extensions for which the compilation + preprocessor pass for
2179 F08 dialect will be used. By default, this is empty.
2180 </para>
2181 </listitem>
2182   </varlistentry>
2183   <varlistentry id="cv-F77">
2184     <term>
2185       <envar>F77</envar>
2186     </term>
2187     <listitem><para>
2188 The Fortran 77 compiler.
2189 You should normally set the &cv-link-FORTRAN; variable,
2190 which specifies the default Fortran compiler
2191 for all Fortran versions.
2192 You only need to set &cv-link-F77; if you need to use a specific compiler
2193 or compiler version for Fortran 77 files.
2194 </para>
2195 </listitem>
2196   </varlistentry>
2197   <varlistentry id="cv-F77COM">
2198     <term>
2199       <envar>F77COM</envar>
2200     </term>
2201     <listitem><para>
2202 The command line used to compile a Fortran 77 source file to an object file.
2203 You only need to set &cv-link-F77COM; if you need to use a specific
2204 command line for Fortran 77 files.
2205 You should normally set the &cv-link-FORTRANCOM; variable,
2206 which specifies the default command line
2207 for all Fortran versions.
2208 </para>
2209 </listitem>
2210   </varlistentry>
2211   <varlistentry id="cv-F77COMSTR">
2212     <term>
2213       <envar>F77COMSTR</envar>
2214     </term>
2215     <listitem><para>
2216 If set, the string displayed when a Fortran 77 source file
2217 is compiled to an object file.
2218 If not set, then &cv-link-F77COM; or &cv-link-FORTRANCOM;
2219 (the command line) is displayed.
2220 </para>
2221 </listitem>
2222   </varlistentry>
2223   <varlistentry id="cv-F77FILESUFFIXES">
2224     <term>
2225       <envar>F77FILESUFFIXES</envar>
2226     </term>
2227     <listitem><para>
2228 The list of file extensions for which the F77 dialect will be used. By
2229 default, this is <literal>['.f77']</literal>
2230 </para>
2231 </listitem>
2232   </varlistentry>
2233   <varlistentry id="cv-F77FLAGS">
2234     <term>
2235       <envar>F77FLAGS</envar>
2236     </term>
2237     <listitem><para>
2238 General user-specified options that are passed to the Fortran 77 compiler.
2239 Note that this variable does
2240 <emphasis>not</emphasis>
2241 contain
2242 <option>-I</option>
2243 (or similar) include search path options
2244 that scons generates automatically from &cv-link-F77PATH;.
2245 See
2246 &cv-link-_F77INCFLAGS;
2247 below,
2248 for the variable that expands to those options.
2249 You only need to set &cv-link-F77FLAGS; if you need to define specific
2250 user options for Fortran 77 files.
2251 You should normally set the &cv-link-FORTRANFLAGS; variable,
2252 which specifies the user-specified options
2253 passed to the default Fortran compiler
2254 for all Fortran versions.
2255 </para>
2256 </listitem>
2257   </varlistentry>
2258   <varlistentry id="cv-_F77INCFLAGS">
2259     <term>
2260       <envar>_F77INCFLAGS</envar>
2261     </term>
2262     <listitem><para>
2263 An automatically-generated construction variable
2264 containing the Fortran 77 compiler command-line options
2265 for specifying directories to be searched for include files.
2266 The value of &cv-link-_F77INCFLAGS; is created
2267 by appending &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
2268 to the beginning and end
2269 of each directory in &cv-link-F77PATH;.
2270 </para>
2271 </listitem>
2272   </varlistentry>
2273   <varlistentry id="cv-F77PATH">
2274     <term>
2275       <envar>F77PATH</envar>
2276     </term>
2277     <listitem><para>
2278 The list of directories that the Fortran 77 compiler will search for include
2279 directories. The implicit dependency scanner will search these
2280 directories for include files. Don't explicitly put include directory
2281 arguments in &cv-link-F77FLAGS; because the result will be non-portable
2282 and the directories will not be searched by the dependency scanner. Note:
2283 directory names in &cv-link-F77PATH; will be looked-up relative to the SConscript
2284 directory when they are used in a command. To force
2285 &scons;
2286 to look-up a directory relative to the root of the source tree use #:
2287 You only need to set &cv-link-F77PATH; if you need to define a specific
2288 include path for Fortran 77 files.
2289 You should normally set the &cv-link-FORTRANPATH; variable,
2290 which specifies the include path
2291 for the default Fortran compiler
2292 for all Fortran versions.
2293 </para>
2294
2295 <example_commands>
2296 env = Environment(F77PATH='#/include')
2297 </example_commands>
2298
2299 <para>
2300 The directory look-up can also be forced using the
2301 &Dir;()
2302 function:
2303 </para>
2304
2305 <example_commands>
2306 include = Dir('include')
2307 env = Environment(F77PATH=include)
2308 </example_commands>
2309
2310 <para>
2311 The directory list will be added to command lines
2312 through the automatically-generated
2313 &cv-link-_F77INCFLAGS;
2314 construction variable,
2315 which is constructed by
2316 appending the values of the
2317 &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
2318 construction variables
2319 to the beginning and end
2320 of each directory in &cv-link-F77PATH;.
2321 Any command lines you define that need
2322 the F77PATH directory list should
2323 include &cv-link-_F77INCFLAGS;:
2324 </para>
2325
2326 <example_commands>
2327 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
2328 </example_commands>
2329 </listitem>
2330   </varlistentry>
2331   <varlistentry id="cv-F77PPCOM">
2332     <term>
2333       <envar>F77PPCOM</envar>
2334     </term>
2335     <listitem><para>
2336 The command line used to compile a Fortran 77 source file to an object file
2337 after first running the file through the C preprocessor.
2338 Any options specified in the &cv-link-F77FLAGS; and &cv-link-CPPFLAGS; construction variables
2339 are included on this command line.
2340 You only need to set &cv-link-F77PPCOM; if you need to use a specific
2341 C-preprocessor command line for Fortran 77 files.
2342 You should normally set the &cv-link-FORTRANPPCOM; variable,
2343 which specifies the default C-preprocessor command line
2344 for all Fortran versions.
2345 </para>
2346 </listitem>
2347   </varlistentry>
2348   <varlistentry id="cv-F77PPCOMSTR">
2349     <term>
2350       <envar>F77PPCOMSTR</envar>
2351     </term>
2352     <listitem><para>
2353 If set, the string displayed when a Fortran 77 source file
2354 is compiled to an object file
2355 after first running the file through the C preprocessor.
2356 If not set, then &cv-link-F77PPCOM; or &cv-link-FORTRANPPCOM;
2357 (the command line) is displayed.
2358 </para>
2359 </listitem>
2360   </varlistentry>
2361   <varlistentry id="cv-F77PPFILESUFFIXES">
2362     <term>
2363       <envar>F77PPFILESUFFIXES</envar>
2364     </term>
2365     <listitem><para>
2366 The list of file extensions for which the compilation + preprocessor pass for
2367 F77 dialect will be used. By default, this is empty.
2368 </para>
2369 </listitem>
2370   </varlistentry>
2371   <varlistentry id="cv-F90">
2372     <term>
2373       <envar>F90</envar>
2374     </term>
2375     <listitem><para>
2376 The Fortran 90 compiler.
2377 You should normally set the &cv-link-FORTRAN; variable,
2378 which specifies the default Fortran compiler
2379 for all Fortran versions.
2380 You only need to set &cv-link-F90; if you need to use a specific compiler
2381 or compiler version for Fortran 90 files.
2382 </para>
2383 </listitem>
2384   </varlistentry>
2385   <varlistentry id="cv-F90COM">
2386     <term>
2387       <envar>F90COM</envar>
2388     </term>
2389     <listitem><para>
2390 The command line used to compile a Fortran 90 source file to an object file.
2391 You only need to set &cv-link-F90COM; if you need to use a specific
2392 command line for Fortran 90 files.
2393 You should normally set the &cv-link-FORTRANCOM; variable,
2394 which specifies the default command line
2395 for all Fortran versions.
2396 </para>
2397 </listitem>
2398   </varlistentry>
2399   <varlistentry id="cv-F90COMSTR">
2400     <term>
2401       <envar>F90COMSTR</envar>
2402     </term>
2403     <listitem><para>
2404 If set, the string displayed when a Fortran 90 source file
2405 is compiled to an object file.
2406 If not set, then &cv-link-F90COM; or &cv-link-FORTRANCOM;
2407 (the command line) is displayed.
2408 </para>
2409 </listitem>
2410   </varlistentry>
2411   <varlistentry id="cv-F90FILESUFFIXES">
2412     <term>
2413       <envar>F90FILESUFFIXES</envar>
2414     </term>
2415     <listitem><para>
2416 The list of file extensions for which the F90 dialect will be used. By
2417 default, this is <literal>['.f90']</literal>
2418 </para>
2419 </listitem>
2420   </varlistentry>
2421   <varlistentry id="cv-F90FLAGS">
2422     <term>
2423       <envar>F90FLAGS</envar>
2424     </term>
2425     <listitem><para>
2426 General user-specified options that are passed to the Fortran 90 compiler.
2427 Note that this variable does
2428 <emphasis>not</emphasis>
2429 contain
2430 <option>-I</option>
2431 (or similar) include search path options
2432 that scons generates automatically from &cv-link-F90PATH;.
2433 See
2434 &cv-link-_F90INCFLAGS;
2435 below,
2436 for the variable that expands to those options.
2437 You only need to set &cv-link-F90FLAGS; if you need to define specific
2438 user options for Fortran 90 files.
2439 You should normally set the &cv-link-FORTRANFLAGS; variable,
2440 which specifies the user-specified options
2441 passed to the default Fortran compiler
2442 for all Fortran versions.
2443 </para>
2444 </listitem>
2445   </varlistentry>
2446   <varlistentry id="cv-_F90INCFLAGS">
2447     <term>
2448       <envar>_F90INCFLAGS</envar>
2449     </term>
2450     <listitem><para>
2451 An automatically-generated construction variable
2452 containing the Fortran 90 compiler command-line options
2453 for specifying directories to be searched for include files.
2454 The value of &cv-link-_F90INCFLAGS; is created
2455 by appending &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
2456 to the beginning and end
2457 of each directory in &cv-link-F90PATH;.
2458 </para>
2459 </listitem>
2460   </varlistentry>
2461   <varlistentry id="cv-F90PATH">
2462     <term>
2463       <envar>F90PATH</envar>
2464     </term>
2465     <listitem><para>
2466 The list of directories that the Fortran 90 compiler will search for include
2467 directories. The implicit dependency scanner will search these
2468 directories for include files. Don't explicitly put include directory
2469 arguments in &cv-link-F90FLAGS; because the result will be non-portable
2470 and the directories will not be searched by the dependency scanner. Note:
2471 directory names in &cv-link-F90PATH; will be looked-up relative to the SConscript
2472 directory when they are used in a command. To force
2473 &scons;
2474 to look-up a directory relative to the root of the source tree use #:
2475 You only need to set &cv-link-F90PATH; if you need to define a specific
2476 include path for Fortran 90 files.
2477 You should normally set the &cv-link-FORTRANPATH; variable,
2478 which specifies the include path
2479 for the default Fortran compiler
2480 for all Fortran versions.
2481 </para>
2482
2483 <example_commands>
2484 env = Environment(F90PATH='#/include')
2485 </example_commands>
2486
2487 <para>
2488 The directory look-up can also be forced using the
2489 &Dir;()
2490 function:
2491 </para>
2492
2493 <example_commands>
2494 include = Dir('include')
2495 env = Environment(F90PATH=include)
2496 </example_commands>
2497
2498 <para>
2499 The directory list will be added to command lines
2500 through the automatically-generated
2501 &cv-link-_F90INCFLAGS;
2502 construction variable,
2503 which is constructed by
2504 appending the values of the
2505 &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
2506 construction variables
2507 to the beginning and end
2508 of each directory in &cv-link-F90PATH;.
2509 Any command lines you define that need
2510 the F90PATH directory list should
2511 include &cv-link-_F90INCFLAGS;:
2512 </para>
2513
2514 <example_commands>
2515 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
2516 </example_commands>
2517 </listitem>
2518   </varlistentry>
2519   <varlistentry id="cv-F90PPCOM">
2520     <term>
2521       <envar>F90PPCOM</envar>
2522     </term>
2523     <listitem><para>
2524 The command line used to compile a Fortran 90 source file to an object file
2525 after first running the file through the C preprocessor.
2526 Any options specified in the &cv-link-F90FLAGS; and &cv-link-CPPFLAGS; construction variables
2527 are included on this command line.
2528 You only need to set &cv-link-F90PPCOM; if you need to use a specific
2529 C-preprocessor command line for Fortran 90 files.
2530 You should normally set the &cv-link-FORTRANPPCOM; variable,
2531 which specifies the default C-preprocessor command line
2532 for all Fortran versions.
2533 </para>
2534 </listitem>
2535   </varlistentry>
2536   <varlistentry id="cv-F90PPCOMSTR">
2537     <term>
2538       <envar>F90PPCOMSTR</envar>
2539     </term>
2540     <listitem><para>
2541 If set, the string displayed when a Fortran 90 source file
2542 is compiled after first running the file through the C preprocessor.
2543 If not set, then &cv-link-F90PPCOM; or &cv-link-FORTRANPPCOM;
2544 (the command line) is displayed.
2545 </para>
2546 </listitem>
2547   </varlistentry>
2548   <varlistentry id="cv-F90PPFILESUFFIXES">
2549     <term>
2550       <envar>F90PPFILESUFFIXES</envar>
2551     </term>
2552     <listitem><para>
2553 The list of file extensions for which the compilation + preprocessor pass for
2554 F90 dialect will be used. By default, this is empty.
2555 </para>
2556 </listitem>
2557   </varlistentry>
2558   <varlistentry id="cv-F95">
2559     <term>
2560       <envar>F95</envar>
2561     </term>
2562     <listitem><para>
2563 The Fortran 95 compiler.
2564 You should normally set the &cv-link-FORTRAN; variable,
2565 which specifies the default Fortran compiler
2566 for all Fortran versions.
2567 You only need to set &cv-link-F95; if you need to use a specific compiler
2568 or compiler version for Fortran 95 files.
2569 </para>
2570 </listitem>
2571   </varlistentry>
2572   <varlistentry id="cv-F95COM">
2573     <term>
2574       <envar>F95COM</envar>
2575     </term>
2576     <listitem><para>
2577 The command line used to compile a Fortran 95 source file to an object file.
2578 You only need to set &cv-link-F95COM; if you need to use a specific
2579 command line for Fortran 95 files.
2580 You should normally set the &cv-link-FORTRANCOM; variable,
2581 which specifies the default command line
2582 for all Fortran versions.
2583 </para>
2584 </listitem>
2585   </varlistentry>
2586   <varlistentry id="cv-F95COMSTR">
2587     <term>
2588       <envar>F95COMSTR</envar>
2589     </term>
2590     <listitem><para>
2591 If set, the string displayed when a Fortran 95 source file
2592 is compiled to an object file.
2593 If not set, then &cv-link-F95COM; or &cv-link-FORTRANCOM;
2594 (the command line) is displayed.
2595 </para>
2596 </listitem>
2597   </varlistentry>
2598   <varlistentry id="cv-F95FILESUFFIXES">
2599     <term>
2600       <envar>F95FILESUFFIXES</envar>
2601     </term>
2602     <listitem><para>
2603 The list of file extensions for which the F95 dialect will be used. By
2604 default, this is <literal>['.f95']</literal>
2605 </para>
2606 </listitem>
2607   </varlistentry>
2608   <varlistentry id="cv-F95FLAGS">
2609     <term>
2610       <envar>F95FLAGS</envar>
2611     </term>
2612     <listitem><para>
2613 General user-specified options that are passed to the Fortran 95 compiler.
2614 Note that this variable does
2615 <emphasis>not</emphasis>
2616 contain
2617 <option>-I</option>
2618 (or similar) include search path options
2619 that scons generates automatically from &cv-link-F95PATH;.
2620 See
2621 &cv-link-_F95INCFLAGS;
2622 below,
2623 for the variable that expands to those options.
2624 You only need to set &cv-link-F95FLAGS; if you need to define specific
2625 user options for Fortran 95 files.
2626 You should normally set the &cv-link-FORTRANFLAGS; variable,
2627 which specifies the user-specified options
2628 passed to the default Fortran compiler
2629 for all Fortran versions.
2630 </para>
2631 </listitem>
2632   </varlistentry>
2633   <varlistentry id="cv-_F95INCFLAGS">
2634     <term>
2635       <envar>_F95INCFLAGS</envar>
2636     </term>
2637     <listitem><para>
2638 An automatically-generated construction variable
2639 containing the Fortran 95 compiler command-line options
2640 for specifying directories to be searched for include files.
2641 The value of &cv-link-_F95INCFLAGS; is created
2642 by appending &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
2643 to the beginning and end
2644 of each directory in &cv-link-F95PATH;.
2645 </para>
2646 </listitem>
2647   </varlistentry>
2648   <varlistentry id="cv-F95PATH">
2649     <term>
2650       <envar>F95PATH</envar>
2651     </term>
2652     <listitem><para>
2653 The list of directories that the Fortran 95 compiler will search for include
2654 directories. The implicit dependency scanner will search these
2655 directories for include files. Don't explicitly put include directory
2656 arguments in &cv-link-F95FLAGS; because the result will be non-portable
2657 and the directories will not be searched by the dependency scanner. Note:
2658 directory names in &cv-link-F95PATH; will be looked-up relative to the SConscript
2659 directory when they are used in a command. To force
2660 &scons;
2661 to look-up a directory relative to the root of the source tree use #:
2662 You only need to set &cv-link-F95PATH; if you need to define a specific
2663 include path for Fortran 95 files.
2664 You should normally set the &cv-link-FORTRANPATH; variable,
2665 which specifies the include path
2666 for the default Fortran compiler
2667 for all Fortran versions.
2668 </para>
2669
2670 <example_commands>
2671 env = Environment(F95PATH='#/include')
2672 </example_commands>
2673
2674 <para>
2675 The directory look-up can also be forced using the
2676 &Dir;()
2677 function:
2678 </para>
2679
2680 <example_commands>
2681 include = Dir('include')
2682 env = Environment(F95PATH=include)
2683 </example_commands>
2684
2685 <para>
2686 The directory list will be added to command lines
2687 through the automatically-generated
2688 &cv-link-_F95INCFLAGS;
2689 construction variable,
2690 which is constructed by
2691 appending the values of the
2692 &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
2693 construction variables
2694 to the beginning and end
2695 of each directory in &cv-link-F95PATH;.
2696 Any command lines you define that need
2697 the F95PATH directory list should
2698 include &cv-link-_F95INCFLAGS;:
2699 </para>
2700
2701 <example_commands>
2702 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
2703 </example_commands>
2704 </listitem>
2705   </varlistentry>
2706   <varlistentry id="cv-F95PPCOM">
2707     <term>
2708       <envar>F95PPCOM</envar>
2709     </term>
2710     <listitem><para>
2711 The command line used to compile a Fortran 95 source file to an object file
2712 after first running the file through the C preprocessor.
2713 Any options specified in the &cv-link-F95FLAGS; and &cv-link-CPPFLAGS; construction variables
2714 are included on this command line.
2715 You only need to set &cv-link-F95PPCOM; if you need to use a specific
2716 C-preprocessor command line for Fortran 95 files.
2717 You should normally set the &cv-link-FORTRANPPCOM; variable,
2718 which specifies the default C-preprocessor command line
2719 for all Fortran versions.
2720 </para>
2721 </listitem>
2722   </varlistentry>
2723   <varlistentry id="cv-F95PPCOMSTR">
2724     <term>
2725       <envar>F95PPCOMSTR</envar>
2726     </term>
2727     <listitem><para>
2728 If set, the string displayed when a Fortran 95 source file
2729 is compiled to an object file
2730 after first running the file through the C preprocessor.
2731 If not set, then &cv-link-F95PPCOM; or &cv-link-FORTRANPPCOM;
2732 (the command line) is displayed.
2733 </para>
2734 </listitem>
2735   </varlistentry>
2736   <varlistentry id="cv-F95PPFILESUFFIXES">
2737     <term>
2738       <envar>F95PPFILESUFFIXES</envar>
2739     </term>
2740     <listitem><para>
2741 The list of file extensions for which the compilation + preprocessor pass for
2742 F95 dialect will be used. By default, this is empty.
2743 </para>
2744 </listitem>
2745   </varlistentry>
2746   <varlistentry id="cv-File">
2747     <term>
2748       <envar>File</envar>
2749     </term>
2750     <listitem><para>
2751 A function that converts a string into a File instance relative to the
2752 target being built.
2753 </para>
2754 </listitem>
2755   </varlistentry>
2756   <varlistentry id="cv-FILE_ENCODING">
2757     <term>
2758       <envar>FILE_ENCODING</envar>
2759     </term>
2760     <listitem><para>
2761 File encoding used for files written by &b-link-Textfile; and &b-link-Substfile;.
2762 Set to "utf-8" by default.
2763 </para>
2764 <para>
2765 <emphasis>New in version  4.5.0.</emphasis>
2766 </para>
2767 </listitem>
2768   </varlistentry>
2769   <varlistentry id="cv-FORTRAN">
2770     <term>
2771       <envar>FORTRAN</envar>
2772     </term>
2773     <listitem><para>
2774 The default Fortran compiler
2775 for all versions of Fortran.
2776 </para>
2777 </listitem>
2778   </varlistentry>
2779   <varlistentry id="cv-FORTRANCOM">
2780     <term>
2781       <envar>FORTRANCOM</envar>
2782     </term>
2783     <listitem><para>
2784 The command line used to compile a Fortran source file to an object file.
2785 By default, any options specified
2786 in the &cv-link-FORTRANFLAGS;,
2787 &cv-link-_FORTRANMODFLAG;, and
2788 &cv-link-_FORTRANINCFLAGS;
2789 &consvars; are included on this command line.
2790 </para>
2791 </listitem>
2792   </varlistentry>
2793   <varlistentry id="cv-FORTRANCOMMONFLAGS">
2794     <term>
2795       <envar>FORTRANCOMMONFLAGS</envar>
2796     </term>
2797     <listitem><para>
2798 General user-specified options that are passed to the Fortran compiler.
2799 Similar to &cv-link-FORTRANFLAGS;,
2800 but this &consvar; is applied to all dialects.
2801 </para>
2802 <para><emphasis>New in version 4.4.</emphasis></para>
2803 </listitem>
2804   </varlistentry>
2805   <varlistentry id="cv-FORTRANCOMSTR">
2806     <term>
2807       <envar>FORTRANCOMSTR</envar>
2808     </term>
2809     <listitem><para>
2810 If set, the string displayed when a Fortran source file
2811 is compiled to an object file.
2812 If not set, then &cv-link-FORTRANCOM;
2813 (the command line) is displayed.
2814 </para>
2815 </listitem>
2816   </varlistentry>
2817   <varlistentry id="cv-FORTRANFILESUFFIXES">
2818     <term>
2819       <envar>FORTRANFILESUFFIXES</envar>
2820     </term>
2821     <listitem><para>
2822 The list of file extensions for which the FORTRAN dialect will be used. By
2823 default, this is <literal>['.f', '.for', '.ftn']</literal>
2824 </para>
2825 </listitem>
2826   </varlistentry>
2827   <varlistentry id="cv-FORTRANFLAGS">
2828     <term>
2829       <envar>FORTRANFLAGS</envar>
2830     </term>
2831     <listitem><para>
2832 General user-specified options for the FORTRAN dialect
2833 that are passed to the Fortran compiler.
2834 Note that this variable does
2835 <emphasis>not</emphasis>
2836 contain
2837 <option>-I</option>
2838 (or similar) include or module search path options
2839 that scons generates automatically from &cv-link-FORTRANPATH;.
2840 See
2841 &cv-link-_FORTRANINCFLAGS; and &cv-link-_FORTRANMODFLAG;
2842 for the &consvars; that expand those options.
2843 </para>
2844 </listitem>
2845   </varlistentry>
2846   <varlistentry id="cv-_FORTRANINCFLAGS">
2847     <term>
2848       <envar>_FORTRANINCFLAGS</envar>
2849     </term>
2850     <listitem><para>
2851 An automatically-generated &consvar;
2852 containing the Fortran compiler command-line options
2853 for specifying directories to be searched for include
2854 files and module files.
2855 The value of &cv-link-_FORTRANINCFLAGS; is created
2856 by respectively prepending and appending
2857 &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
2858 to the beginning and end
2859 of each directory in &cv-link-FORTRANPATH;.
2860 </para>
2861 </listitem>
2862   </varlistentry>
2863   <varlistentry id="cv-FORTRANMODDIR">
2864     <term>
2865       <envar>FORTRANMODDIR</envar>
2866     </term>
2867     <listitem><para>
2868 Directory location where the Fortran compiler should place
2869 any module files it generates.  This variable is empty, by default. Some
2870 Fortran compilers will internally append this directory in the search path
2871 for module files, as well.
2872 </para>
2873 </listitem>
2874   </varlistentry>
2875   <varlistentry id="cv-FORTRANMODDIRPREFIX">
2876     <term>
2877       <envar>FORTRANMODDIRPREFIX</envar>
2878     </term>
2879     <listitem><para>
2880 The prefix used to specify a module directory on the Fortran compiler command
2881 line.
2882 This will be prepended to the beginning of the directory
2883 in the &cv-link-FORTRANMODDIR; &consvars;
2884 when the &cv-link-_FORTRANMODFLAG; variables is automatically generated.
2885 </para>
2886 </listitem>
2887   </varlistentry>
2888   <varlistentry id="cv-FORTRANMODDIRSUFFIX">
2889     <term>
2890       <envar>FORTRANMODDIRSUFFIX</envar>
2891     </term>
2892     <listitem><para>
2893 The suffix used to specify a module directory on the Fortran compiler command
2894 line.
2895 This will be appended to the end of the directory
2896 in the &cv-link-FORTRANMODDIR; &consvars;
2897 when the &cv-link-_FORTRANMODFLAG; variables is automatically generated.
2898 </para>
2899 </listitem>
2900   </varlistentry>
2901   <varlistentry id="cv-_FORTRANMODFLAG">
2902     <term>
2903       <envar>_FORTRANMODFLAG</envar>
2904     </term>
2905     <listitem><para>
2906 An automatically-generated &consvar;
2907 containing the Fortran compiler command-line option
2908 for specifying the directory location where the Fortran
2909 compiler should place any module files that happen to get
2910 generated during compilation.
2911 The value of &cv-link-_FORTRANMODFLAG; is created
2912 by respectively prepending and appending
2913 &cv-link-FORTRANMODDIRPREFIX; and &cv-link-FORTRANMODDIRSUFFIX;
2914 to the beginning and end of the directory in &cv-link-FORTRANMODDIR;.
2915 </para>
2916 </listitem>
2917   </varlistentry>
2918   <varlistentry id="cv-FORTRANMODPREFIX">
2919     <term>
2920       <envar>FORTRANMODPREFIX</envar>
2921     </term>
2922     <listitem><para>
2923 The module file prefix used by the Fortran compiler.  SCons assumes that
2924 the Fortran compiler follows the quasi-standard naming convention for
2925 module files of
2926 <filename>module_name.mod</filename>.
2927 As a result, this variable is left empty, by default.  For situations in
2928 which the compiler does not necessarily follow the normal convention,
2929 the user may use this variable.  Its value will be appended to every
2930 module file name as scons attempts to resolve dependencies.
2931 </para>
2932 </listitem>
2933   </varlistentry>
2934   <varlistentry id="cv-FORTRANMODSUFFIX">
2935     <term>
2936       <envar>FORTRANMODSUFFIX</envar>
2937     </term>
2938     <listitem><para>
2939 The module file suffix used by the Fortran compiler.  SCons assumes that
2940 the Fortran compiler follows the quasi-standard naming convention for
2941 module files of
2942 <filename>module_name.mod</filename>.
2943 As a result, this variable is set to ".mod", by default.  For situations
2944 in which the compiler does not necessarily follow the normal convention,
2945 the user may use this variable.  Its value will be appended to every
2946 module file name as scons attempts to resolve dependencies.
2947 </para>
2948 </listitem>
2949   </varlistentry>
2950   <varlistentry id="cv-FORTRANPATH">
2951     <term>
2952       <envar>FORTRANPATH</envar>
2953     </term>
2954     <listitem><para>
2955 The list of directories that the Fortran compiler will search for
2956 include files and (for some compilers) module files. The Fortran implicit
2957 dependency scanner will search these directories for include files (but
2958 not module files since they are autogenerated and, as such, may not
2959 actually exist at the time the scan takes place). Don't explicitly put
2960 include directory arguments in FORTRANFLAGS because the result will be
2961 non-portable and the directories will not be searched by the dependency
2962 scanner. Note: directory names in FORTRANPATH will be looked-up relative
2963 to the SConscript directory when they are used in a command. To force
2964 &scons;
2965 to look-up a directory relative to the root of the source tree use #:
2966 </para>
2967
2968 <example_commands>
2969 env = Environment(FORTRANPATH='#/include')
2970 </example_commands>
2971
2972 <para>
2973 The directory look-up can also be forced using the
2974 &Dir;()
2975 function:
2976 </para>
2977
2978 <example_commands>
2979 include = Dir('include')
2980 env = Environment(FORTRANPATH=include)
2981 </example_commands>
2982
2983 <para>
2984 The directory list will be added to command lines
2985 through the automatically-generated
2986 &cv-link-_FORTRANINCFLAGS;
2987 &consvar;,
2988 which is constructed by
2989 respectively prepending and appending the values of the
2990 &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
2991 &consvars;
2992 to the beginning and end
2993 of each directory in &cv-link-FORTRANPATH;.
2994 Any command lines you define that need
2995 the FORTRANPATH directory list should
2996 include &cv-link-_FORTRANINCFLAGS;:
2997 </para>
2998
2999 <example_commands>
3000 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
3001 </example_commands>
3002 </listitem>
3003   </varlistentry>
3004   <varlistentry id="cv-FORTRANPPCOM">
3005     <term>
3006       <envar>FORTRANPPCOM</envar>
3007     </term>
3008     <listitem><para>
3009 The command line used to compile a Fortran source file to an object file
3010 after first running the file through the C preprocessor.
3011 By default, any options specified in the &cv-link-FORTRANFLAGS;,
3012 &cv-link-CPPFLAGS;,
3013 &cv-link-_CPPDEFFLAGS;,
3014 &cv-link-_FORTRANMODFLAG;, and
3015 &cv-link-_FORTRANINCFLAGS;
3016 &consvars; are included on this command line.
3017 </para>
3018 </listitem>
3019   </varlistentry>
3020   <varlistentry id="cv-FORTRANPPCOMSTR">
3021     <term>
3022       <envar>FORTRANPPCOMSTR</envar>
3023     </term>
3024     <listitem><para>
3025 If set, the string displayed when a Fortran source file
3026 is compiled to an object file
3027 after first running the file through the C preprocessor.
3028 If not set, then &cv-link-FORTRANPPCOM;
3029 (the command line) is displayed.
3030 </para>
3031 </listitem>
3032   </varlistentry>
3033   <varlistentry id="cv-FORTRANPPFILESUFFIXES">
3034     <term>
3035       <envar>FORTRANPPFILESUFFIXES</envar>
3036     </term>
3037     <listitem><para>
3038 The list of file extensions for which the compilation + preprocessor pass for
3039 FORTRAN dialect will be used. By default, this is <literal>['.fpp', '.FPP']</literal>
3040 </para>
3041 </listitem>
3042   </varlistentry>
3043   <varlistentry id="cv-FORTRANSUFFIXES">
3044     <term>
3045       <envar>FORTRANSUFFIXES</envar>
3046     </term>
3047     <listitem><para>
3048 The list of suffixes of files that will be scanned
3049 for Fortran implicit dependencies
3050 (INCLUDE lines and USE statements).
3051 The default list is:
3052 </para>
3053
3054 <example_commands>
3055 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
3056 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
3057 </example_commands>
3058 </listitem>
3059   </varlistentry>
3060   <varlistentry id="cv-FRAMEWORKPATH">
3061     <term>
3062       <envar>FRAMEWORKPATH</envar>
3063     </term>
3064     <listitem><para>
3065                 On Mac OS X with gcc,
3066                 a list containing the paths to search for frameworks.
3067                 Used by the compiler to find framework-style includes like
3068                 #include &lt;Fmwk/Header.h&gt;.
3069                 Used by the linker to find user-specified frameworks when linking (see
3070                 &cv-link-FRAMEWORKS;).
3071                 For example:
3072             </para>
3073
3074             <example_commands>
3075 env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
3076             </example_commands>
3077
3078             <para>
3079                 will add
3080             </para>
3081
3082             <example_commands>
3083 ... -Fmyframeworkdir
3084             </example_commands>
3085
3086             <para>
3087                 to the compiler and linker command lines.
3088             </para>
3089         </listitem>
3090   </varlistentry>
3091   <varlistentry id="cv-_FRAMEWORKPATH">
3092     <term>
3093       <envar>_FRAMEWORKPATH</envar>
3094     </term>
3095     <listitem><para>
3096                 On Mac OS X with gcc, an automatically-generated construction variable
3097                 containing the linker command-line options corresponding to
3098                 &cv-link-FRAMEWORKPATH;.
3099             </para>
3100         </listitem>
3101   </varlistentry>
3102   <varlistentry id="cv-FRAMEWORKPATHPREFIX">
3103     <term>
3104       <envar>FRAMEWORKPATHPREFIX</envar>
3105     </term>
3106     <listitem><para>
3107                 On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries.
3108                 (see &cv-link-FRAMEWORKPATH;).
3109                 The default value is
3110                 <option>-F</option>.
3111             </para>
3112         </listitem>
3113   </varlistentry>
3114   <varlistentry id="cv-FRAMEWORKPREFIX">
3115     <term>
3116       <envar>FRAMEWORKPREFIX</envar>
3117     </term>
3118     <listitem><para>
3119                 On Mac OS X with gcc,
3120                 the prefix to be used for linking in frameworks
3121                 (see &cv-link-FRAMEWORKS;).
3122                 The default value is
3123                 <option>-framework</option>.
3124             </para>
3125         </listitem>
3126   </varlistentry>
3127   <varlistentry id="cv-FRAMEWORKS">
3128     <term>
3129       <envar>FRAMEWORKS</envar>
3130     </term>
3131     <listitem><para>
3132                 On Mac OS X with gcc, a list of the framework names to be linked into a
3133                 program or shared library or bundle.
3134                 The default value is the empty list.
3135                 For example:
3136             </para>
3137
3138             <example_commands>
3139 env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
3140             </example_commands>
3141
3142         </listitem>
3143   </varlistentry>
3144   <varlistentry id="cv-_FRAMEWORKS">
3145     <term>
3146       <envar>_FRAMEWORKS</envar>
3147     </term>
3148     <listitem><para>
3149                 On Mac OS X with gcc,
3150                 an automatically-generated construction variable
3151                 containing the linker command-line options
3152                 for linking with FRAMEWORKS.
3153             </para>
3154         </listitem>
3155   </varlistentry>
3156   <varlistentry id="cv-FRAMEWORKSFLAGS">
3157     <term>
3158       <envar>FRAMEWORKSFLAGS</envar>
3159     </term>
3160     <listitem><para>
3161                 On Mac OS X with gcc,
3162                 general user-supplied frameworks options to be added at
3163                 the end of a command
3164                 line building a loadable module.
3165                 (This has been largely superseded by
3166                 the &cv-link-FRAMEWORKPATH;, &cv-link-FRAMEWORKPATHPREFIX;,
3167                 &cv-link-FRAMEWORKPREFIX; and &cv-link-FRAMEWORKS; variables
3168                 described above.)
3169             </para>
3170         </listitem>
3171   </varlistentry>
3172   <varlistentry id="cv-GS">
3173     <term>
3174       <envar>GS</envar>
3175     </term>
3176     <listitem><para>
3177 The Ghostscript program used to, for example, convert PostScript to PDF files.
3178 </para>
3179 </listitem>
3180   </varlistentry>
3181   <varlistentry id="cv-GSCOM">
3182     <term>
3183       <envar>GSCOM</envar>
3184     </term>
3185     <listitem><para>
3186 The full Ghostscript command line used for the conversion process. Its default
3187 value is <quote><literal>$GS $GSFLAGS -sOutputFile=$TARGET $SOURCES</literal></quote>.
3188 </para>
3189 </listitem>
3190   </varlistentry>
3191   <varlistentry id="cv-GSCOMSTR">
3192     <term>
3193       <envar>GSCOMSTR</envar>
3194     </term>
3195     <listitem><para>
3196 The string displayed when
3197 Ghostscript is called for the conversion process.
3198 If this is not set (the default), then &cv-link-GSCOM; (the command line) is displayed.
3199 </para>
3200 </listitem>
3201   </varlistentry>
3202   <varlistentry id="cv-GSFLAGS">
3203     <term>
3204       <envar>GSFLAGS</envar>
3205     </term>
3206     <listitem><para>
3207 General options passed to the Ghostscript program,
3208 when converting PostScript to PDF files for example. Its default value
3209 is <quote><literal>-dNOPAUSE -dBATCH -sDEVICE=pdfwrite</literal></quote>
3210 </para>
3211 </listitem>
3212   </varlistentry>
3213   <varlistentry id="cv-HOST_ARCH">
3214     <term>
3215       <envar>HOST_ARCH</envar>
3216     </term>
3217     <listitem><para>
3218       The name of the host hardware architecture
3219       used to create this &consenv;.
3220       The platform code sets this when initializing
3221       (see &cv-link-PLATFORM; and the
3222       <parameter>platform</parameter> argument to &f-link-Environment;).
3223       Note the detected name of the architecture may not be identical to
3224       that returned by the &Python;
3225       <systemitem>platform.machine</systemitem> method.
3226     </para>
3227     <para>
3228       On the <literal>win32</literal> platform,
3229       if the &MSVC; compiler is available,
3230       &t-link-msvc; tool setup is done using
3231       &cv-HOST_ARCH; and &cv-link-TARGET_ARCH;.
3232       Changing the values at any later time will not cause
3233       the tool to be reinitialized.
3234       Valid host arch values are
3235       <literal>x86</literal> and <literal>arm</literal>
3236       for 32-bit hosts and
3237       <literal>amd64</literal>, <literal>arm64</literal>,
3238       and <literal>x86_64</literal> for 64-bit hosts.
3239     </para>
3240     <para>
3241       Should be considered immutable.
3242       &cv-HOST_ARCH; is not currently used by other platforms,
3243       but the option is reserved to do so in future
3244     </para>
3245   </listitem>
3246   </varlistentry>
3247   <varlistentry id="cv-HOST_OS">
3248     <term>
3249       <envar>HOST_OS</envar>
3250     </term>
3251     <listitem><para>
3252       The name of the host operating system for the platform
3253       used to create this &consenv;.
3254       The platform code sets this when initializing
3255       (see &cv-link-PLATFORM; and the
3256       <parameter>platform</parameter> argument to &f-link-Environment;).
3257     </para>
3258     <para>
3259       Should be considered immutable.
3260       &cv-HOST_OS; is not currently used by &SCons;,
3261       but the option is reserved to do so in future
3262     </para>
3263   </listitem>
3264   </varlistentry>
3265   <varlistentry id="cv-IDLSUFFIXES">
3266     <term>
3267       <envar>IDLSUFFIXES</envar>
3268     </term>
3269     <listitem><para>
3270 The list of suffixes of files that will be scanned
3271 for IDL implicit dependencies
3272 (#include or import lines).
3273 The default list is:
3274 </para>
3275
3276 <example_commands>
3277 [".idl", ".IDL"]
3278 </example_commands>
3279 </listitem>
3280   </varlistentry>
3281   <varlistentry id="cv-IMPLIBNOVERSIONSYMLINKS">
3282     <term>
3283       <envar>IMPLIBNOVERSIONSYMLINKS</envar>
3284     </term>
3285     <listitem><para>
3286 Used to override &cv-link-SHLIBNOVERSIONSYMLINKS;/&cv-link-LDMODULENOVERSIONSYMLINKS; when
3287 creating versioned import library for a shared library/loadable module. If not defined,
3288 then &cv-link-SHLIBNOVERSIONSYMLINKS;/&cv-link-LDMODULENOVERSIONSYMLINKS; is used to determine
3289 whether to disable symlink generation or not.
3290 </para>
3291 </listitem>
3292   </varlistentry>
3293   <varlistentry id="cv-IMPLIBPREFIX">
3294     <term>
3295       <envar>IMPLIBPREFIX</envar>
3296     </term>
3297     <listitem><para>
3298 The prefix used for import library names. For example, cygwin uses import
3299 libraries (<literal>libfoo.dll.a</literal>) in pair with dynamic libraries
3300 (<literal>cygfoo.dll</literal>). The &t-link-cyglink; linker sets
3301 &cv-link-IMPLIBPREFIX; to <literal>'lib'</literal> and &cv-link-SHLIBPREFIX;
3302 to <literal>'cyg'</literal>.
3303 </para>
3304 </listitem>
3305   </varlistentry>
3306   <varlistentry id="cv-IMPLIBSUFFIX">
3307     <term>
3308       <envar>IMPLIBSUFFIX</envar>
3309     </term>
3310     <listitem><para>
3311 The suffix used for import library names. For example, cygwin uses import
3312 libraries (<literal>libfoo.dll.a</literal>) in pair with dynamic libraries
3313 (<literal>cygfoo.dll</literal>). The &t-link-cyglink; linker sets
3314 &cv-link-IMPLIBSUFFIX; to <literal>'.dll.a'</literal> and &cv-link-SHLIBSUFFIX;
3315 to <literal>'.dll'</literal>.
3316 </para>
3317 </listitem>
3318   </varlistentry>
3319   <varlistentry id="cv-IMPLIBVERSION">
3320     <term>
3321       <envar>IMPLIBVERSION</envar>
3322     </term>
3323     <listitem><para>
3324 Used to override &cv-link-SHLIBVERSION;/&cv-link-LDMODULEVERSION; when
3325 generating versioned import library for a shared library/loadable module. If
3326 undefined, the &cv-link-SHLIBVERSION;/&cv-link-LDMODULEVERSION; is used to
3327 determine the version of versioned import library.
3328 </para>
3329 </listitem>
3330   </varlistentry>
3331   <varlistentry id="cv-IMPLICIT_COMMAND_DEPENDENCIES">
3332     <term>
3333       <envar>IMPLICIT_COMMAND_DEPENDENCIES</envar>
3334     </term>
3335     <listitem><para>
3336 Controls whether or not &SCons; will
3337 add implicit dependencies for the commands
3338 executed to build targets.
3339 </para>
3340
3341 <para>
3342 By default, &SCons; will add to each target
3343 an implicit dependency on the command
3344 represented by the first argument of any
3345 command line it executes (which is typically
3346 the command itself). By setting such
3347 a dependency, &SCons; can determine that
3348 a target should be rebuilt if the command changes,
3349 such as when a compiler is upgraded to a new version.
3350 The specific file for the dependency is
3351 found by searching the
3352 <varname>PATH</varname>
3353 variable in the
3354 <varname>ENV</varname> dictionary
3355 in the &consenv; used to execute the command.
3356 The default is the same as
3357 setting the &consvar;
3358 &cv-IMPLICIT_COMMAND_DEPENDENCIES;
3359 to a True-like value (<quote>true</quote>,
3360 <quote>yes</quote>,
3361 or <quote>1</quote> - but not a number
3362 greater than one, as that has a different meaning).
3363 </para>
3364
3365 <para>
3366 Action strings can be segmented by the
3367 use of an AND operator, <literal>&amp;&amp;</literal>.
3368 In a segemented string, each segment is a separate
3369 <quote>command line</quote>, these are run
3370 sequentially until one fails or the entire
3371 sequence has been executed. If an
3372 action string is segmented, then the selected
3373 behavior of &cv-IMPLICIT_COMMAND_DEPENDENCIES;
3374 is applied to each segment.
3375 </para>
3376
3377 <para>
3378 If &cv-IMPLICIT_COMMAND_DEPENDENCIES;
3379 is set to a False-like value
3380 (<quote>none</quote>,
3381 <quote>false</quote>,
3382 <quote>no</quote>,
3383 <quote>0</quote>,
3384 etc.),
3385 then the implicit dependency will
3386 not be added to the targets
3387 built with that &consenv;.
3388 </para>
3389
3390 <para>
3391 If &cv-IMPLICIT_COMMAND_DEPENDENCIES;
3392 is set to <quote>2</quote> or higher,
3393 then that number of arguments in the command line
3394 will be scanned for relative or absolute paths.
3395 If any are present, they will be added as
3396 implicit dependencies to the targets built
3397 with that &consenv;.
3398 The first argument in the command line will be
3399 searched for using the <varname>PATH</varname>
3400 variable in the <varname>ENV</varname> dictionary
3401 in the &consenv; used to execute the command.
3402 The other arguments will only be found if they
3403 are absolute paths or valid paths relative
3404 to the working directory.
3405 </para>
3406
3407 <para>
3408 If &cv-IMPLICIT_COMMAND_DEPENDENCIES;
3409 is set to <quote>all</quote>,
3410 then all arguments in the command line will be
3411 scanned for relative or absolute paths.
3412 If any are present, they will be added as
3413 implicit dependencies to the targets built
3414 with that &consenv;.
3415 The first argument in the command line will be
3416 searched for using the <varname>PATH</varname>
3417 variable in the <varname>ENV</varname> dictionary
3418 in the &consenv; used to execute the command.
3419 The other arguments will only be found if they
3420 are absolute paths or valid paths relative
3421 to the working directory.
3422 </para>
3423
3424 <example_commands>
3425 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES=False)
3426 </example_commands>
3427 </listitem>
3428   </varlistentry>
3429   <varlistentry id="cv-INCPREFIX">
3430     <term>
3431       <envar>INCPREFIX</envar>
3432     </term>
3433     <listitem><para>
3434 The prefix used to specify an include directory on the C compiler command
3435 line.
3436 This will be prepended to each directory
3437 in the &cv-link-CPPPATH; and &cv-link-FORTRANPATH; &consvars;
3438 when the &cv-link-_CPPINCFLAGS; and &cv-link-_FORTRANINCFLAGS;
3439 variables are automatically generated.
3440 </para>
3441 </listitem>
3442   </varlistentry>
3443   <varlistentry id="cv-INCSUFFIX">
3444     <term>
3445       <envar>INCSUFFIX</envar>
3446     </term>
3447     <listitem><para>
3448 The suffix used to specify an include directory on the C compiler command
3449 line.
3450 This will be appended to each directory
3451 in the &cv-link-CPPPATH; and &cv-link-FORTRANPATH; &consvars;
3452 when the &cv-link-_CPPINCFLAGS; and &cv-link-_FORTRANINCFLAGS;
3453 variables are automatically generated.
3454 </para>
3455 </listitem>
3456   </varlistentry>
3457   <varlistentry id="cv-INSTALL">
3458     <term>
3459       <envar>INSTALL</envar>
3460     </term>
3461     <listitem><para>
3462 A function to be called to install a file into a
3463 destination file name.
3464 The default function copies the file into the destination
3465 (and sets the destination file's mode and permission bits
3466 to match the source file's).
3467 The function takes the following arguments:
3468 </para>
3469
3470 <example_commands>
3471 def install(dest, source, env):
3472 </example_commands>
3473
3474 <para>
3475 <varname>dest</varname>
3476 is the path name of the destination file.
3477 <varname>source</varname>
3478 is the path name of the source file.
3479 <varname>env</varname>
3480 is the construction environment
3481 (a dictionary of construction values)
3482 in force for this file installation.
3483 </para>
3484 </listitem>
3485   </varlistentry>
3486   <varlistentry id="cv-INSTALLSTR">
3487     <term>
3488       <envar>INSTALLSTR</envar>
3489     </term>
3490     <listitem><para>
3491 The string displayed when a file is
3492 installed into a destination file name.
3493 The default is:
3494 </para>
3495 <example_commands>
3496 Install file: "$SOURCE" as "$TARGET"
3497 </example_commands>
3498 </listitem>
3499   </varlistentry>
3500   <varlistentry id="cv-INTEL_C_COMPILER_VERSION">
3501     <term>
3502       <envar>INTEL_C_COMPILER_VERSION</envar>
3503     </term>
3504     <listitem><para>
3505 Set by the &t-link-intelc; Tool
3506 to the major version number of the Intel C compiler
3507 selected for use.
3508 </para>
3509 </listitem>
3510   </varlistentry>
3511   <varlistentry id="cv-JAR">
3512     <term>
3513       <envar>JAR</envar>
3514     </term>
3515     <listitem><para>
3516 The Java archive tool.
3517 </para>
3518 </listitem>
3519   </varlistentry>
3520   <varlistentry id="cv-JARCHDIR">
3521     <term>
3522       <envar>JARCHDIR</envar>
3523     </term>
3524     <listitem><para>
3525 The directory to which the Java archive tool should change
3526 (using the
3527 <option>-C</option>
3528 option).
3529 </para>
3530 </listitem>
3531   </varlistentry>
3532   <varlistentry id="cv-JARCOM">
3533     <term>
3534       <envar>JARCOM</envar>
3535     </term>
3536     <listitem><para>
3537 The command line used to call the Java archive tool.
3538 </para>
3539 </listitem>
3540   </varlistentry>
3541   <varlistentry id="cv-JARCOMSTR">
3542     <term>
3543       <envar>JARCOMSTR</envar>
3544     </term>
3545     <listitem><para>
3546 The string displayed when the Java archive tool
3547 is called
3548 If this is not set, then &cv-link-JARCOM; (the command line) is displayed.
3549 </para>
3550
3551 <example_commands>
3552 env = Environment(JARCOMSTR="JARchiving $SOURCES into $TARGET")
3553 </example_commands>
3554 </listitem>
3555   </varlistentry>
3556   <varlistentry id="cv-JARFLAGS">
3557     <term>
3558       <envar>JARFLAGS</envar>
3559     </term>
3560     <listitem><para>
3561 General options passed to the Java archive tool.
3562 By default this is set to
3563 <option>cf</option>
3564 to create the necessary
3565 <command>jar</command>
3566 file.
3567 </para>
3568 </listitem>
3569   </varlistentry>
3570   <varlistentry id="cv-JARSUFFIX">
3571     <term>
3572       <envar>JARSUFFIX</envar>
3573     </term>
3574     <listitem><para>
3575 The suffix for Java archives:
3576 <filename>.jar</filename>
3577 by default.
3578 </para>
3579 </listitem>
3580   </varlistentry>
3581   <varlistentry id="cv-JAVABOOTCLASSPATH">
3582     <term>
3583       <envar>JAVABOOTCLASSPATH</envar>
3584     </term>
3585     <listitem><para>
3586                 Specifies the location of the bootstrap class files.
3587                 Can be specified as a string or Node object,
3588                 or as a list of strings or Node objects.
3589             </para>
3590             <para>
3591                 The value will be added to the JDK command lines
3592                 via the <option>-bootclasspath</option> option,
3593                 which requires a system-specific search path separator.
3594                 This will be supplied by &SCons; as needed when it
3595                 constructs the command line if &cv-JAVABOOTCLASSPATH; is
3596                 provided in list form.
3597                 If &cv-JAVABOOTCLASSPATH; is a single string containing
3598                 search path separator characters
3599                 (<literal>:</literal> for POSIX systems or
3600                 <literal>;</literal> for Windows), it will not be modified;
3601                 and so is inherently system-specific;
3602                 to supply the path in a system-independent manner,
3603                 give &cv-JAVABOOTCLASSPATH; as a list of paths instead.
3604             </para>
3605             <note>
3606                 <para>
3607                     Can only be used when compiling for releases prior to JDK 9.
3608                 </para>
3609             </note>
3610         </listitem>
3611   </varlistentry>
3612   <varlistentry id="cv-JAVAC">
3613     <term>
3614       <envar>JAVAC</envar>
3615     </term>
3616     <listitem><para>
3617                 The Java compiler.
3618             </para>
3619         </listitem>
3620   </varlistentry>
3621   <varlistentry id="cv-JAVACCOM">
3622     <term>
3623       <envar>JAVACCOM</envar>
3624     </term>
3625     <listitem><para>
3626                 The command line used to compile a directory tree containing
3627                 Java source files to
3628                 corresponding Java class files.
3629                 Any options specified in the &cv-link-JAVACFLAGS; construction variable
3630                 are included on this command line.
3631             </para>
3632         </listitem>
3633   </varlistentry>
3634   <varlistentry id="cv-JAVACCOMSTR">
3635     <term>
3636       <envar>JAVACCOMSTR</envar>
3637     </term>
3638     <listitem><para>
3639                 The string displayed when compiling
3640                 a directory tree of Java source files to
3641                 corresponding Java class files.
3642                 If this is not set, then &cv-link-JAVACCOM; (the command line) is displayed.
3643             </para>
3644
3645             <example_commands>
3646 env = Environment(JAVACCOMSTR="Compiling class files $TARGETS from $SOURCES")
3647             </example_commands>
3648         </listitem>
3649   </varlistentry>
3650   <varlistentry id="cv-JAVACFLAGS">
3651     <term>
3652       <envar>JAVACFLAGS</envar>
3653     </term>
3654     <listitem><para>
3655                 General options that are passed to the Java compiler.
3656             </para>
3657         </listitem>
3658   </varlistentry>
3659   <varlistentry id="cv-JAVACLASSDIR">
3660     <term>
3661       <envar>JAVACLASSDIR</envar>
3662     </term>
3663     <listitem><para>
3664                 The directory in which Java class files may be found.
3665                 This is stripped from the beginning of any Java
3666                 <filename>.class</filename>
3667                 file names supplied to the &b-link-JavaH; builder.
3668             </para>
3669         </listitem>
3670   </varlistentry>
3671   <varlistentry id="cv-JAVACLASSPATH">
3672     <term>
3673       <envar>JAVACLASSPATH</envar>
3674     </term>
3675     <listitem><para>
3676                 Specifies the class search path for the JDK tools.
3677                 Can be specified as a string or Node object,
3678                 or as a list of strings or Node objects.
3679                 Class path entries may be directory names to search
3680                 for class files or packages, pathnames to archives
3681                 (<filename>.jar</filename> or <filename>.zip</filename>)
3682                 containing classes, or paths ending in a "base name wildcard"
3683                 character (<literal>*</literal>), which matches files
3684                 in that directory with a <filename>.jar</filename> suffix.
3685                 See the Java documentation for more details.
3686             </para>
3687             <para>
3688                 The value will be added to the JDK command lines
3689                 via the <option>-classpath</option> option,
3690                 which requires a system-specific search path separator.
3691                 This will be supplied by &SCons; as needed when it
3692                 constructs the command line if &cv-JAVACLASSPATH; is
3693                 provided in list form.
3694                 If &cv-JAVACLASSPATH; is a single string containing
3695                 search path separator characters
3696                 (<literal>:</literal> for POSIX systems or
3697                 <literal>;</literal> for Windows),
3698                 it will be split on the separator into a list of individual
3699                 paths for dependency scanning purposes.
3700                 It will not be modified for JDK command-line usage,
3701                 so such a string is inherently system-specific;
3702                 to supply the path in a system-independent manner,
3703                 give &cv-JAVACLASSPATH; as a list of paths instead.
3704             </para>
3705             <note>
3706               <para>
3707                 &SCons; <emphasis role="bold">always</emphasis>
3708                 supplies a <option>-sourcepath</option>
3709                 when invoking the Java compiler &javac;,
3710                 regardless of the setting of &cv-link-JAVASOURCEPATH;,
3711                 as it passes the path(s) to the source(s) supplied
3712                 in the call to the &b-link-Java; builder via
3713                 <option>-sourcepath</option> .
3714                 From the documentation of the standard Java toolkit for &javac;:
3715                 <quote>If not compiling code for modules, if the
3716                 <option>--source-path</option> or <option>-sourcepath</option>
3717                 option is not specified, then the user class path is also
3718                 searched for source files.</quote>
3719                 Since <option>-sourcepath</option> is always supplied,
3720                 &javac; will not use the contents of the value of
3721                 &cv-JAVACLASSPATH; when searching for sources.
3722               </para>
3723             </note>
3724         </listitem>
3725   </varlistentry>
3726   <varlistentry id="cv-JAVACLASSSUFFIX">
3727     <term>
3728       <envar>JAVACLASSSUFFIX</envar>
3729     </term>
3730     <listitem><para>
3731                 The suffix for Java class files;
3732                 <filename>.class</filename>
3733                 by default.
3734             </para>
3735         </listitem>
3736   </varlistentry>
3737   <varlistentry id="cv-JAVAH">
3738     <term>
3739       <envar>JAVAH</envar>
3740     </term>
3741     <listitem><para>
3742 The Java generator for C header and stub files.
3743 </para>
3744 </listitem>
3745   </varlistentry>
3746   <varlistentry id="cv-JAVAHCOM">
3747     <term>
3748       <envar>JAVAHCOM</envar>
3749     </term>
3750     <listitem><para>
3751 The command line used to generate C header and stub files
3752 from Java classes.
3753 Any options specified in the &cv-link-JAVAHFLAGS; construction variable
3754 are included on this command line.
3755 </para>
3756 </listitem>
3757   </varlistentry>
3758   <varlistentry id="cv-JAVAHCOMSTR">
3759     <term>
3760       <envar>JAVAHCOMSTR</envar>
3761     </term>
3762     <listitem><para>
3763 The string displayed when C header and stub files
3764 are generated from Java classes.
3765 If this is not set, then &cv-link-JAVAHCOM; (the command line) is displayed.
3766 </para>
3767
3768 <example_commands>
3769 env = Environment(JAVAHCOMSTR="Generating header/stub file(s) $TARGETS from $SOURCES")
3770 </example_commands>
3771 </listitem>
3772   </varlistentry>
3773   <varlistentry id="cv-JAVAHFLAGS">
3774     <term>
3775       <envar>JAVAHFLAGS</envar>
3776     </term>
3777     <listitem><para>
3778 General options passed to the C header and stub file generator
3779 for Java classes.
3780 </para>
3781 </listitem>
3782   </varlistentry>
3783   <varlistentry id="cv-JAVAINCLUDES">
3784     <term>
3785       <envar>JAVAINCLUDES</envar>
3786     </term>
3787     <listitem><para>
3788                 Include path for Java header files
3789                 (such as <filename>jni.h</filename>).
3790             </para>
3791         </listitem>
3792   </varlistentry>
3793   <varlistentry id="cv-JAVAPROCESSORPATH">
3794     <term>
3795       <envar>JAVAPROCESSORPATH</envar>
3796     </term>
3797     <listitem><para>
3798                 Specifies the location of the annotation processor class files.
3799                 Can be specified as a string or Node object,
3800                 or as a list of strings or Node objects.
3801             </para>
3802             <para>
3803                 The value will be added to the JDK command lines
3804                 via the <option>-processorpath</option> option,
3805                 which requires a system-specific search path separator.
3806                 This will be supplied by &SCons; as needed when it
3807                 constructs the command line if &cv-JAVAPROCESSORPATH; is
3808                 provided in list form.
3809                 If &cv-JAVAPROCESSORPATH; is a single string containing
3810                 search path separator characters
3811                 (<literal>:</literal> for POSIX systems or
3812                 <literal>;</literal> for Windows), it will not be modified;
3813                 and so is inherently system-specific;
3814                 to supply the path in a system-independent manner,
3815                 give &cv-JAVAPROCESSORPATH; as a list of paths instead.
3816             </para>
3817             <para>
3818                 <emphasis>New in version 4.5.0</emphasis>
3819             </para>
3820         </listitem>
3821   </varlistentry>
3822   <varlistentry id="cv-JAVASOURCEPATH">
3823     <term>
3824       <envar>JAVASOURCEPATH</envar>
3825     </term>
3826     <listitem><para>
3827                 Specifies the list of directories that
3828                 will be searched for input (source)
3829                 <filename>.java</filename> files.
3830                 Can be specified as a string or Node object,
3831                 or as a list of strings or Node objects.
3832             </para>
3833             <para>
3834                 The value will be added to the JDK command lines
3835                 via the <option>-sourcepath</option> option,
3836                 which requires a system-specific search path separator,
3837                 This will be supplied by &SCons; as needed when it
3838                 constructs the command line if &cv-JAVASOURCEPATH; is
3839                 provided in list form.
3840                 If &cv-JAVASOURCEPATH; is a single string containing
3841                 search path separator characters
3842                 (<literal>:</literal> for POSIX systems or
3843                 <literal>;</literal> for Windows), it will not be modified,
3844                 and so is inherently system-specific;
3845                 to supply the path in a system-independent manner,
3846                 give &cv-JAVASOURCEPATH; as a list of paths instead.
3847             </para>
3848             <para>
3849                 Note that the specified directories are only added to
3850                 the command line via the <option>-sourcepath</option> option.
3851                 &SCons; does not currently search the
3852                 &cv-JAVASOURCEPATH; directories for dependent
3853                 <filename>.java</filename>
3854                 files.
3855             </para>
3856         </listitem>
3857   </varlistentry>
3858   <varlistentry id="cv-JAVASUFFIX">
3859     <term>
3860       <envar>JAVASUFFIX</envar>
3861     </term>
3862     <listitem><para>
3863                 The suffix for Java files;
3864                 <filename>.java</filename>
3865                 by default.
3866             </para>
3867         </listitem>
3868   </varlistentry>
3869   <varlistentry id="cv-JAVAVERSION">
3870     <term>
3871       <envar>JAVAVERSION</envar>
3872     </term>
3873     <listitem><para>
3874                 Specifies the Java version being used by the &b-link-Java;
3875                 builder. Set this to specify the version of Java targeted
3876                 by the &javac; compiler.
3877                 This is sometimes necessary because
3878                 Java 1.5 changed the file names that are created
3879                 for nested anonymous inner classes,
3880                 which can cause a mismatch with the files
3881                 that &SCons; expects will be generated by the &javac; compiler.
3882                 Setting &cv-JAVAVERSION; to a version greater than
3883                 <literal>1.4</literal> makes &SCons; realize that a build
3884                 with such a compiler is actually up to date.
3885                 The default is <literal>1.4</literal>.
3886             </para>
3887             <para>
3888                 While this is <emphasis>not</emphasis> primarily intended for
3889                 selecting one version of the Java compiler vs. another,
3890                 it does have that effect on the Windows platform. A
3891                 more precise approach is to set &cv-link-JAVAC; (and related
3892                 &consvars; for related utilities) to the path to the specific
3893                 Java compiler you want, if that is not the default compiler.
3894                 On non-Windows platforms, the
3895                 <systemitem>alternatives</systemitem> system may provide a
3896                 way to adjust the default Java compiler without
3897                 having to specify explicit paths.
3898             </para>
3899         </listitem>
3900   </varlistentry>
3901   <varlistentry id="cv-LATEX">
3902     <term>
3903       <envar>LATEX</envar>
3904     </term>
3905     <listitem><para>
3906 The LaTeX structured formatter and typesetter.
3907 </para>
3908 </listitem>
3909   </varlistentry>
3910   <varlistentry id="cv-LATEXCOM">
3911     <term>
3912       <envar>LATEXCOM</envar>
3913     </term>
3914     <listitem><para>
3915 The command line used to call the LaTeX structured formatter and typesetter.
3916 </para>
3917 </listitem>
3918   </varlistentry>
3919   <varlistentry id="cv-LATEXCOMSTR">
3920     <term>
3921       <envar>LATEXCOMSTR</envar>
3922     </term>
3923     <listitem><para>
3924 The string displayed when calling
3925 the LaTeX structured formatter and typesetter.
3926 If this is not set, then &cv-link-LATEXCOM; (the command line) is displayed.
3927 </para>
3928
3929 <example_commands>
3930 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
3931 </example_commands>
3932 </listitem>
3933   </varlistentry>
3934   <varlistentry id="cv-LATEXFLAGS">
3935     <term>
3936       <envar>LATEXFLAGS</envar>
3937     </term>
3938     <listitem><para>
3939 General options passed to the LaTeX structured formatter and typesetter.
3940 </para>
3941 </listitem>
3942   </varlistentry>
3943   <varlistentry id="cv-LATEXRETRIES">
3944     <term>
3945       <envar>LATEXRETRIES</envar>
3946     </term>
3947     <listitem><para>
3948 The maximum number of times that LaTeX
3949 will be re-run if the
3950 <filename>.log</filename>
3951 generated by the &cv-link-LATEXCOM; command
3952 indicates that there are undefined references.
3953 The default is to try to resolve undefined references
3954 by re-running LaTeX up to three times.
3955 </para>
3956 </listitem>
3957   </varlistentry>
3958   <varlistentry id="cv-LATEXSUFFIXES">
3959     <term>
3960       <envar>LATEXSUFFIXES</envar>
3961     </term>
3962     <listitem><para>
3963 The list of suffixes of files that will be scanned
3964 for LaTeX implicit dependencies
3965 (<literal>\include</literal> or <literal>\import</literal> files).
3966 The default list is:
3967 </para>
3968
3969 <example_commands>
3970 [".tex", ".ltx", ".latex"]
3971 </example_commands>
3972 </listitem>
3973   </varlistentry>
3974   <varlistentry id="cv-LDMODULE">
3975     <term>
3976       <envar>LDMODULE</envar>
3977     </term>
3978     <listitem><para>
3979 The linker for building loadable modules.
3980 By default, this is the same as &cv-link-SHLINK;.
3981 </para>
3982 </listitem>
3983   </varlistentry>
3984   <varlistentry id="cv-LDMODULECOM">
3985     <term>
3986       <envar>LDMODULECOM</envar>
3987     </term>
3988     <listitem><para>
3989 The command line for building loadable modules.
3990 On Mac OS X, this uses the &cv-link-LDMODULE;,
3991 &cv-link-LDMODULEFLAGS; and
3992 &cv-link-FRAMEWORKSFLAGS; variables.
3993 On other systems, this is the same as &cv-link-SHLINK;.
3994 </para>
3995 </listitem>
3996   </varlistentry>
3997   <varlistentry id="cv-LDMODULECOMSTR">
3998     <term>
3999       <envar>LDMODULECOMSTR</envar>
4000     </term>
4001     <listitem><para>
4002 If set, the string displayed when building loadable modules.
4003 If not set, then &cv-link-LDMODULECOM; (the command line) is displayed.
4004 </para>
4005 </listitem>
4006   </varlistentry>
4007   <varlistentry id="cv-LDMODULEEMITTER">
4008     <term>
4009       <envar>LDMODULEEMITTER</envar>
4010     </term>
4011     <listitem><para>
4012 Contains the emitter specification for the
4013 &b-link-LoadableModule; builder.
4014 The manpage section "Builder Objects" contains
4015 general information on specifying emitters.
4016 </para>
4017 </listitem>
4018   </varlistentry>
4019   <varlistentry id="cv-LDMODULEFLAGS">
4020     <term>
4021       <envar>LDMODULEFLAGS</envar>
4022     </term>
4023     <listitem><para>
4024 General user options passed to the linker for building loadable modules.
4025 </para>
4026 </listitem>
4027   </varlistentry>
4028   <varlistentry id="cv-LDMODULENOVERSIONSYMLINKS">
4029     <term>
4030       <envar>LDMODULENOVERSIONSYMLINKS</envar>
4031     </term>
4032     <listitem><para>
4033 Instructs the &b-link-LoadableModule; builder to not automatically create symlinks
4034 for versioned modules. Defaults to <literal>$SHLIBNOVERSIONSYMLINKS</literal>
4035 </para>
4036 </listitem>
4037   </varlistentry>
4038   <varlistentry id="cv-LDMODULEPREFIX">
4039     <term>
4040       <envar>LDMODULEPREFIX</envar>
4041     </term>
4042     <listitem><para>
4043 The prefix used for loadable module file names.
4044 On Mac OS X, this is null;
4045 on other systems, this is
4046 the same as &cv-link-SHLIBPREFIX;.
4047 </para>
4048 </listitem>
4049   </varlistentry>
4050   <varlistentry id="cv-_LDMODULESONAME">
4051     <term>
4052       <envar>_LDMODULESONAME</envar>
4053     </term>
4054     <listitem><para>
4055 A macro that automatically generates loadable module's SONAME based on $TARGET,
4056 $LDMODULEVERSION and $LDMODULESUFFIX. Used by &b-link-LoadableModule; builder
4057 when the linker tool supports SONAME (e.g. &t-link-gnulink;).
4058 </para>
4059 </listitem>
4060   </varlistentry>
4061   <varlistentry id="cv-LDMODULESUFFIX">
4062     <term>
4063       <envar>LDMODULESUFFIX</envar>
4064     </term>
4065     <listitem><para>
4066 The suffix used for loadable module file names.
4067 On Mac OS X, this is null;
4068 on other systems, this is
4069 the same as $SHLIBSUFFIX.
4070 </para>
4071 </listitem>
4072   </varlistentry>
4073   <varlistentry id="cv-LDMODULEVERSION">
4074     <term>
4075       <envar>LDMODULEVERSION</envar>
4076     </term>
4077     <listitem><para>
4078 When this &consvar; is defined, a versioned loadable module
4079 is created by &b-link-LoadableModule; builder. This activates the
4080 &cv-link-_LDMODULEVERSIONFLAGS; and thus modifies the &cv-link-LDMODULECOM; as
4081 required, adds the version number to the library name, and creates the symlinks
4082 that are needed. &cv-link-LDMODULEVERSION; versions should exist in the same
4083 format as &cv-link-SHLIBVERSION;.
4084 </para>
4085 </listitem>
4086   </varlistentry>
4087   <varlistentry id="cv-_LDMODULEVERSIONFLAGS">
4088     <term>
4089       <envar>_LDMODULEVERSIONFLAGS</envar>
4090     </term>
4091     <listitem><para>
4092 This macro automatically introduces extra flags to &cv-link-LDMODULECOM; when
4093 building versioned &b-link-LoadableModule; (that is when
4094 &cv-link-LDMODULEVERSION; is set). <literal>_LDMODULEVERSIONFLAGS</literal>
4095 usually adds &cv-link-SHLIBVERSIONFLAGS; and some extra dynamically generated
4096 options (such as <literal>-Wl,-soname=$_LDMODULESONAME</literal>).  It is unused
4097 by plain (unversioned) loadable modules.
4098 </para>
4099 </listitem>
4100   </varlistentry>
4101   <varlistentry id="cv-LDMODULEVERSIONFLAGS">
4102     <term>
4103       <envar>LDMODULEVERSIONFLAGS</envar>
4104     </term>
4105     <listitem><para>
4106 Extra flags added to &cv-link-LDMODULECOM; when building versioned
4107 &b-link-LoadableModule;. These flags are only used when &cv-link-LDMODULEVERSION; is
4108 set.
4109 </para>
4110 </listitem>
4111   </varlistentry>
4112   <varlistentry id="cv-LEX">
4113     <term>
4114       <envar>LEX</envar>
4115     </term>
4116     <listitem><para>
4117 The lexical analyzer generator.
4118 </para>
4119 </listitem>
4120   </varlistentry>
4121   <varlistentry id="cv-LEX_HEADER_FILE">
4122     <term>
4123       <envar>LEX_HEADER_FILE</envar>
4124     </term>
4125     <listitem><para>
4126 If supplied, generate a C header file with the name taken from this variable.
4127 Will be emitted as a <option>--header-file=</option>
4128 command-line option. Use this in preference to including
4129 <option>--header-file=</option> in &cv-link-LEXFLAGS; directly.
4130 </para>
4131 </listitem>
4132   </varlistentry>
4133   <varlistentry id="cv-LEX_TABLES_FILE">
4134     <term>
4135       <envar>LEX_TABLES_FILE</envar>
4136     </term>
4137     <listitem><para>
4138 If supplied, write the lex tables to a file with the name
4139 taken from this variable.
4140 Will be emitted as a <option>--tables-file=</option>
4141 command-line option. Use this in preference to including
4142 <option>--tables-file=</option> in &cv-link-LEXFLAGS; directly.
4143 </para>
4144 </listitem>
4145   </varlistentry>
4146   <varlistentry id="cv-LEXCOM">
4147     <term>
4148       <envar>LEXCOM</envar>
4149     </term>
4150     <listitem><para>
4151 The command line used to call the lexical analyzer generator
4152 to generate a source file.
4153 </para>
4154 </listitem>
4155   </varlistentry>
4156   <varlistentry id="cv-LEXCOMSTR">
4157     <term>
4158       <envar>LEXCOMSTR</envar>
4159     </term>
4160     <listitem><para>
4161 The string displayed when generating a source file
4162 using the lexical analyzer generator.
4163 If this is not set, then &cv-link-LEXCOM; (the command line) is displayed.
4164 </para>
4165
4166 <example_commands>
4167 env = Environment(LEXCOMSTR="Lex'ing $TARGET from $SOURCES")
4168 </example_commands>
4169 </listitem>
4170   </varlistentry>
4171   <varlistentry id="cv-LEXFLAGS">
4172     <term>
4173       <envar>LEXFLAGS</envar>
4174     </term>
4175     <listitem><para>
4176 General options passed to the lexical analyzer generator.
4177 In addition to passing the value on during invocation,
4178 the &t-link-lex; tool also examines this &consvar; for options
4179 which cause additional output files to be generated,
4180 and adds those to the target list.
4181 Recognized for this purpose are GNU &flex; options
4182 <option>--header-file=</option> and
4183 <option>--tables-file=</option>;
4184 the output file is named by the option argument.
4185 </para>
4186 <para>
4187 Note that files specified by <option>--header-file=</option> and
4188 <option>--tables-file=</option> may not be properly handled
4189 by &SCons; in all situations. Consider using
4190 &cv-link-LEX_HEADER_FILE; and &cv-link-LEX_TABLES_FILE; instead.
4191 </para>
4192 </listitem>
4193   </varlistentry>
4194   <varlistentry id="cv-LEXUNISTD">
4195     <term>
4196       <envar>LEXUNISTD</envar>
4197     </term>
4198     <listitem><para>
4199 Used only on windows environments to set a lex flag to prevent 'unistd.h' from being included. The default value is '--nounistd'.
4200 </para>
4201 </listitem>
4202   </varlistentry>
4203   <varlistentry id="cv-_LIBDIRFLAGS">
4204     <term>
4205       <envar>_LIBDIRFLAGS</envar>
4206     </term>
4207     <listitem><para>
4208 An automatically-generated construction variable
4209 containing the linker command-line options
4210 for specifying directories to be searched for library.
4211 The value of &cv-_LIBDIRFLAGS; is created
4212 by respectively prepending and appending &cv-link-LIBDIRPREFIX;
4213 and &cv-link-LIBDIRSUFFIX;
4214 to each directory in &cv-link-LIBPATH;.
4215 </para>
4216 </listitem>
4217   </varlistentry>
4218   <varlistentry id="cv-LIBDIRPREFIX">
4219     <term>
4220       <envar>LIBDIRPREFIX</envar>
4221     </term>
4222     <listitem><para>
4223 The prefix used to specify a library directory on the linker command line.
4224 This will be prepended to each directory
4225 in the &cv-link-LIBPATH; construction variable
4226 when the &cv-link-_LIBDIRFLAGS; variable is automatically generated.
4227 </para>
4228 </listitem>
4229   </varlistentry>
4230   <varlistentry id="cv-LIBDIRSUFFIX">
4231     <term>
4232       <envar>LIBDIRSUFFIX</envar>
4233     </term>
4234     <listitem><para>
4235 The suffix used to specify a library directory on the linker command line.
4236 This will be appended to each directory
4237 in the &cv-link-LIBPATH; construction variable
4238 when the &cv-link-_LIBDIRFLAGS; variable is automatically generated.
4239 </para>
4240 </listitem>
4241   </varlistentry>
4242   <varlistentry id="cv-LIBEMITTER">
4243     <term>
4244       <envar>LIBEMITTER</envar>
4245     </term>
4246     <listitem><para>
4247 Contains the emitter specification for the
4248 &b-link-StaticLibrary; builder.
4249 The manpage section "Builder Objects" contains
4250 general information on specifying emitters.
4251 </para>
4252 </listitem>
4253   </varlistentry>
4254   <varlistentry id="cv-_LIBFLAGS">
4255     <term>
4256       <envar>_LIBFLAGS</envar>
4257     </term>
4258     <listitem><para>
4259 An automatically-generated construction variable
4260 containing the linker command-line options
4261 for specifying libraries to be linked with the resulting target.
4262 The value of &cv-_LIBFLAGS; is created
4263 by respectively prepending and appending &cv-link-LIBLINKPREFIX;
4264 and &cv-link-LIBLINKSUFFIX;
4265 to each filename in &cv-link-LIBS;.
4266 </para>
4267 </listitem>
4268   </varlistentry>
4269   <varlistentry id="cv-LIBLINKPREFIX">
4270     <term>
4271       <envar>LIBLINKPREFIX</envar>
4272     </term>
4273     <listitem><para>
4274 The prefix used to specify a library to link on the linker command line.
4275 This will be prepended to each library
4276 in the &cv-link-LIBS; construction variable
4277 when the &cv-link-_LIBFLAGS; variable is automatically generated.
4278 </para>
4279 </listitem>
4280   </varlistentry>
4281   <varlistentry id="cv-LIBLINKSUFFIX">
4282     <term>
4283       <envar>LIBLINKSUFFIX</envar>
4284     </term>
4285     <listitem><para>
4286 The suffix used to specify a library to link on the linker command line.
4287 This will be appended to each library
4288 in the &cv-link-LIBS; construction variable
4289 when the &cv-link-_LIBFLAGS; variable is automatically generated.
4290 </para>
4291 </listitem>
4292   </varlistentry>
4293   <varlistentry id="cv-LIBLITERALPREFIX">
4294     <term>
4295       <envar>LIBLITERALPREFIX</envar>
4296     </term>
4297     <listitem><para>
4298 If the linker supports command line syntax directing
4299 that the argument specifying a library should be
4300 searched for literally (without modification),
4301 &cv-LIBLITERALPREFIX; can be set to that indicator.
4302 For example, the GNU linker follows this rule:
4303 <quote>
4304 <literal>-l:foo</literal> searches the library path
4305 for a filename called <literal>foo</literal>,
4306 without converting it to
4307 <literal>libfoo.so</literal> or
4308 <literal>libfoo.a</literal>.
4309 </quote>
4310 If &cv-LIBLITERALPREFIX; is set,
4311 &SCons; will not transform a string-valued entry in
4312 &cv-link-LIBS; that starts with that string.
4313 The entry will still be surrounded with
4314 &cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX;
4315 on the command line.
4316 This is useful, for example,
4317 in directing that a static library
4318 be used when both a static and dynamic library are available
4319 and linker policy is to prefer dynamic libraries.
4320 Compared to the example in &cv-link-LIBS;,
4321 </para>
4322 <example_commands>
4323 env.Append(LIBS=":libmylib.a")
4324 </example_commands>
4325 <para>
4326 will let the linker select that specific (static)
4327 library name if found in the library search path.
4328 This differs from using a
4329 <classname>File</classname> object
4330 to specify the static library,
4331 as the latter bypasses the library search path entirely.
4332 </para>
4333 </listitem>
4334   </varlistentry>
4335   <varlistentry id="cv-LIBPATH">
4336     <term>
4337       <envar>LIBPATH</envar>
4338     </term>
4339     <listitem><para>
4340 The list of directories that will be searched for libraries
4341 specified by the &cv-link-LIBS; &consvar;.
4342 &cv-LIBPATH; should be a list of path strings,
4343 or a single string, not a pathname list joined by
4344 Python's <systemitem>os.pathsep</systemitem>.
4345 <!-- XXX OLD
4346 The implicit dependency scanner will search these
4347 directories for include files. Don't explicitly put include directory
4348 arguments into &cv-LINKFLAGS; or &cv-SHLINKFLAGS;
4349 because the result will be non-portable
4350 and the directories will not be searched by the dependency scanner.
4351 -->
4352 <!-- XXX NEW -->
4353 Do not put library search directives directly
4354 into &cv-LINKFLAGS; or &cv-SHLINKFLAGS;
4355 as the result will be non-portable.
4356 <!-- end NEW -->
4357 </para>
4358
4359 <para>
4360 Note:
4361 directory names in &cv-LIBPATH; will be looked-up relative to the
4362 directory of the SConscript file
4363 when they are used in a command.
4364 To force &scons;
4365 to look-up a directory relative to the root of the source tree use
4366 the <literal>#</literal> prefix:
4367 </para>
4368
4369 <example_commands>
4370 env = Environment(LIBPATH='#/libs')
4371 </example_commands>
4372
4373 <para>
4374 The directory look-up can also be forced using the
4375 &f-link-Dir; function:
4376 </para>
4377
4378 <example_commands>
4379 libs = Dir('libs')
4380 env = Environment(LIBPATH=libs)
4381 </example_commands>
4382
4383 <para>
4384 The directory list will be added to command lines
4385 through the automatically-generated
4386 &cv-link-_LIBDIRFLAGS;
4387 construction variable,
4388 which is constructed by
4389 respectively prepending and appending the values of the
4390 &cv-link-LIBDIRPREFIX; and &cv-link-LIBDIRSUFFIX;
4391 construction variables
4392 to each directory in &cv-LIBPATH;.
4393 Any command lines you define that need
4394 the &cv-LIBPATH; directory list should
4395 include &cv-_LIBDIRFLAGS;:
4396 </para>
4397
4398 <example_commands>
4399 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
4400 </example_commands>
4401 </listitem>
4402   </varlistentry>
4403   <varlistentry id="cv-LIBPREFIX">
4404     <term>
4405       <envar>LIBPREFIX</envar>
4406     </term>
4407     <listitem><para>
4408 The prefix used for (static) library file names.
4409 A default value is set for each platform
4410 (posix, win32, os2, etc.),
4411 but the value is overridden by individual tools
4412 (ar, mslib, sgiar, sunar, tlib, etc.)
4413 to reflect the names of the libraries they create.
4414 </para>
4415 </listitem>
4416   </varlistentry>
4417   <varlistentry id="cv-LIBPREFIXES">
4418     <term>
4419       <envar>LIBPREFIXES</envar>
4420     </term>
4421     <listitem><para>
4422 A list of all legal prefixes for library file names
4423 on the current platform.
4424 When searching for library dependencies,
4425 SCons will look for files with these prefixes,
4426 the base library name,
4427 and suffixes from the &cv-link-LIBSUFFIXES; list.
4428 </para>
4429 </listitem>
4430   </varlistentry>
4431   <varlistentry id="cv-LIBS">
4432     <term>
4433       <envar>LIBS</envar>
4434     </term>
4435     <listitem><para>
4436 The list of libraries
4437 that will be added to the link line
4438 for linking with any executable program, shared library, or loadable module
4439 created by the &consenv; or override.
4440 </para>
4441
4442 <para>
4443 For portability,
4444 a string-valued library name should include
4445 only the base library name,
4446 without prefixes such as <filename>lib</filename>
4447 or suffixes such as <filename>.so</filename> or <filename>.dll</filename>.
4448 &SCons; <emphasis>will</emphasis> attempt to
4449 strip prefixes from the &cv-link-LIBPREFIXES; list
4450 and suffixes from the &cv-link-LIBSUFFIXES; list,
4451 but depending on that behavior will make the build
4452 less portable:
4453 for example, on a POSIX system,
4454 no attempt will be made to strip a suffix like
4455 <filename>.dll</filename>.
4456 Library name strings in &cv-LIBS; should not include a path component:
4457 instead use &cv-link-LIBPATH; to direct the compiler
4458 to look for libraries in those paths,
4459 plus any default paths the linker searches in.
4460 If &cv-link-LIBLITERALPREFIX; is set to a non-empty string,
4461 then a string-valued &cv-LIBS; entry
4462 that starts with &cv-link-LIBLITERALPREFIX;
4463 will cause the rest of the entry
4464 to be searched for for unmodified,
4465 but respecting normal library search paths
4466 (this is an exception to the guideline above
4467 about leaving off the prefix/suffix from the library name).
4468 </para>
4469
4470 <para>
4471 If a &cv-LIBS; entry is a Node object
4472 (either as returned by a previous Builder call,
4473 or as the result of an explicit call to &f-link-File;),
4474 the pathname from that Node will be added to
4475 &cv-_LIBFLAGS;,
4476 and thus to the link line,
4477 unmodified - without adding
4478 &cv-LIBLINKPREFIX;
4479 or
4480 &cv-LIBLINKSUFFIX;.
4481 Such entries are searched for literally
4482 (including any path component);
4483 the library search paths are not used.
4484 For example:
4485 </para>
4486
4487 <example_commands>
4488 env.Append(LIBS=File('/tmp/mylib.so'))
4489 </example_commands>
4490
4491 <para>
4492 <!-- is this actually true? -->
4493 For each &Builder; call that causes linking with libraries,
4494 &SCons; will add the libraries in the setting of &cv-LIBS;
4495 in effect at that moment to the dependecy graph
4496 as dependencies of the target being generated.
4497 </para>
4498
4499 <para>
4500 The library list will transformed to command line
4501 arguments through the automatically-generated
4502 &cv-link-_LIBFLAGS; &consvar;
4503 which is constructed by
4504 respectively prepending and appending the values of the
4505 &cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX; &consvars;
4506 to each library name.
4507 </para>
4508
4509 <para>
4510 Any command lines you define yourself that need
4511 the libraries from &cv-LIBS; should include &cv-_LIBFLAGS;
4512 (as well as &cv-link-_LIBDIRFLAGS;)
4513 rather than &cv-LIBS;.
4514 For example:
4515 </para>
4516
4517 <example_commands>
4518 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
4519 </example_commands>
4520 </listitem>
4521   </varlistentry>
4522   <varlistentry id="cv-LIBSUFFIX">
4523     <term>
4524       <envar>LIBSUFFIX</envar>
4525     </term>
4526     <listitem><para>
4527 The suffix used for (static) library file names.
4528 A default value is set for each platform
4529 (posix, win32, os2, etc.),
4530 but the value is overridden by individual tools
4531 (ar, mslib, sgiar, sunar, tlib, etc.)
4532 to reflect the names of the libraries they create.
4533 </para>
4534 </listitem>
4535   </varlistentry>
4536   <varlistentry id="cv-LIBSUFFIXES">
4537     <term>
4538       <envar>LIBSUFFIXES</envar>
4539     </term>
4540     <listitem><para>
4541 A list of all legal suffixes for library file names.
4542 on the current platform.
4543 When searching for library dependencies,
4544 SCons will look for files with prefixes from the &cv-link-LIBPREFIXES; list,
4545 the base library name,
4546 and these suffixes.
4547 </para>
4548 </listitem>
4549   </varlistentry>
4550   <varlistentry id="cv-LICENSE">
4551     <term>
4552       <envar>LICENSE</envar>
4553     </term>
4554     <listitem><para>
4555 The abbreviated name, preferably the SPDX code, of the license under which
4556 this project is released (GPL-3.0, LGPL-2.1, BSD-2-Clause etc.).
4557 See
4558 <ulink url="http://www.opensource.org/licenses/alphabetical">
4559 http://www.opensource.org/licenses/alphabetical</ulink>
4560 for a list of license names and SPDX codes.
4561 </para>
4562 <para>See the &b-link-Package; builder.</para>
4563 </listitem>
4564   </varlistentry>
4565   <varlistentry id="cv-LINESEPARATOR">
4566     <term>
4567       <envar>LINESEPARATOR</envar>
4568     </term>
4569     <listitem><para>
4570 The separator used by the &b-link-Substfile; and &b-link-Textfile; builders.
4571 This value is used between sources when constructing the target.
4572 It defaults to the current system line separator.
4573 </para>
4574 </listitem>
4575   </varlistentry>
4576   <varlistentry id="cv-LINGUAS_FILE">
4577     <term>
4578       <envar>LINGUAS_FILE</envar>
4579     </term>
4580     <listitem><para>
4581 The &cv-LINGUAS_FILE; defines file(s) containing list of additional linguas
4582 to be processed by &b-link-POInit;, &b-link-POUpdate; or &b-link-MOFiles;
4583 builders. It also affects &b-link-Translate; builder. If the variable contains
4584 a string, it defines name of the list file. The &cv-LINGUAS_FILE; may be a
4585 list of file names as well. If &cv-LINGUAS_FILE; is set to
4586 <literal>True</literal> (or non-zero numeric value), the list will be read from
4587 default file named
4588 <filename>LINGUAS</filename>.
4589 </para>
4590
4591 </listitem>
4592   </varlistentry>
4593   <varlistentry id="cv-LINK">
4594     <term>
4595       <envar>LINK</envar>
4596     </term>
4597     <listitem><para>
4598 The linker.
4599 See also &cv-link-SHLINK; for linking shared objects.
4600 </para>
4601 <para>
4602 On POSIX systems (those using the &t-link-link; tool),
4603 you should normally not change this value as it defaults
4604 to a "smart" linker tool which selects a compiler
4605 driver matching the type of source files in use.
4606 So for example, if you set &cv-link-CXX; to a specific
4607 compiler name, and are compiling C++ sources,
4608 the smartlink function will automatically select the same compiler
4609 for linking.
4610 </para>
4611 </listitem>
4612   </varlistentry>
4613   <varlistentry id="cv-LINKCOM">
4614     <term>
4615       <envar>LINKCOM</envar>
4616     </term>
4617     <listitem><para>
4618 The command line used to link object files into an executable.
4619 See also &cv-link-SHLINKCOM; for linking shared objects.
4620 </para>
4621 </listitem>
4622   </varlistentry>
4623   <varlistentry id="cv-LINKCOMSTR">
4624     <term>
4625       <envar>LINKCOMSTR</envar>
4626     </term>
4627     <listitem><para>
4628 If set, the string displayed when object files
4629 are linked into an executable.
4630 If not set, then &cv-link-LINKCOM; (the command line) is displayed.
4631 See also &cv-link-SHLINKCOMSTR;.  for linking shared objects.
4632 </para>
4633
4634 <example_commands>
4635 env = Environment(LINKCOMSTR = "Linking $TARGET")
4636 </example_commands>
4637 </listitem>
4638   </varlistentry>
4639   <varlistentry id="cv-LINKFLAGS">
4640     <term>
4641       <envar>LINKFLAGS</envar>
4642     </term>
4643     <listitem><para>
4644 General user options passed to the linker.
4645 Note that this variable should
4646 <emphasis>not</emphasis>
4647 contain
4648 <option>-l</option>
4649 (or similar) options for linking with the libraries listed in &cv-link-LIBS;,
4650 nor
4651 <option>-L</option>
4652 (or similar) library search path options
4653 that scons generates automatically from &cv-link-LIBPATH;.
4654 See
4655 &cv-link-_LIBFLAGS;
4656 above,
4657 for the variable that expands to library-link options,
4658 and
4659 &cv-link-_LIBDIRFLAGS;
4660 above,
4661 for the variable that expands to library search path options.
4662 See also &cv-link-SHLINKFLAGS;.  for linking shared objects.
4663 </para>
4664 </listitem>
4665   </varlistentry>
4666   <varlistentry id="cv-M4">
4667     <term>
4668       <envar>M4</envar>
4669     </term>
4670     <listitem><para>
4671 The M4 macro preprocessor.
4672 </para>
4673 </listitem>
4674   </varlistentry>
4675   <varlistentry id="cv-M4COM">
4676     <term>
4677       <envar>M4COM</envar>
4678     </term>
4679     <listitem><para>
4680 The command line used to pass files through the M4 macro preprocessor.
4681 </para>
4682 </listitem>
4683   </varlistentry>
4684   <varlistentry id="cv-M4COMSTR">
4685     <term>
4686       <envar>M4COMSTR</envar>
4687     </term>
4688     <listitem><para>
4689 The string displayed when
4690 a file is passed through the M4 macro preprocessor.
4691 If this is not set, then &cv-link-M4COM; (the command line) is displayed.
4692 </para>
4693 </listitem>
4694   </varlistentry>
4695   <varlistentry id="cv-M4FLAGS">
4696     <term>
4697       <envar>M4FLAGS</envar>
4698     </term>
4699     <listitem><para>
4700 General options passed to the M4 macro preprocessor.
4701 </para>
4702 </listitem>
4703   </varlistentry>
4704   <varlistentry id="cv-MAKEINDEX">
4705     <term>
4706       <envar>MAKEINDEX</envar>
4707     </term>
4708     <listitem><para>
4709 The makeindex generator for the TeX formatter and typesetter and the
4710 LaTeX structured formatter and typesetter.
4711 </para>
4712 </listitem>
4713   </varlistentry>
4714   <varlistentry id="cv-MAKEINDEXCOM">
4715     <term>
4716       <envar>MAKEINDEXCOM</envar>
4717     </term>
4718     <listitem><para>
4719 The command line used to call the makeindex generator for the
4720 TeX formatter and typesetter and the LaTeX structured formatter and
4721 typesetter.
4722 </para>
4723 </listitem>
4724   </varlistentry>
4725   <varlistentry id="cv-MAKEINDEXCOMSTR">
4726     <term>
4727       <envar>MAKEINDEXCOMSTR</envar>
4728     </term>
4729     <listitem><para>
4730 The string displayed when calling the makeindex generator for the
4731 TeX formatter and typesetter
4732 and the LaTeX structured formatter and typesetter.
4733 If this is not set, then &cv-link-MAKEINDEXCOM; (the command line) is displayed.
4734 </para>
4735 </listitem>
4736   </varlistentry>
4737   <varlistentry id="cv-MAKEINDEXFLAGS">
4738     <term>
4739       <envar>MAKEINDEXFLAGS</envar>
4740     </term>
4741     <listitem><para>
4742 General options passed to the makeindex generator for the TeX formatter
4743 and typesetter and the LaTeX structured formatter and typesetter.
4744 </para>
4745 </listitem>
4746   </varlistentry>
4747   <varlistentry id="cv-MAXLINELENGTH">
4748     <term>
4749       <envar>MAXLINELENGTH</envar>
4750     </term>
4751     <listitem><para>
4752 The maximum number of characters allowed on an external command line.
4753 On Win32 systems,
4754 link lines longer than this many characters
4755 are linked via a temporary file name.
4756 </para>
4757 </listitem>
4758   </varlistentry>
4759   <varlistentry id="cv-MIDL">
4760     <term>
4761       <envar>MIDL</envar>
4762     </term>
4763     <listitem><para>
4764 The Microsoft IDL compiler.
4765 </para>
4766 </listitem>
4767   </varlistentry>
4768   <varlistentry id="cv-MIDLCOM">
4769     <term>
4770       <envar>MIDLCOM</envar>
4771     </term>
4772     <listitem><para>
4773 The command line used to pass files to the Microsoft IDL compiler.
4774 </para>
4775 </listitem>
4776   </varlistentry>
4777   <varlistentry id="cv-MIDLCOMSTR">
4778     <term>
4779       <envar>MIDLCOMSTR</envar>
4780     </term>
4781     <listitem><para>
4782 The string displayed when
4783 the Microsoft IDL compiler is called.
4784 If this is not set, then &cv-link-MIDLCOM; (the command line) is displayed.
4785 </para>
4786 </listitem>
4787   </varlistentry>
4788   <varlistentry id="cv-MIDLFLAGS">
4789     <term>
4790       <envar>MIDLFLAGS</envar>
4791     </term>
4792     <listitem><para>
4793 General options passed to the Microsoft IDL compiler.
4794 </para>
4795 </listitem>
4796   </varlistentry>
4797   <varlistentry id="cv-MOSUFFIX">
4798     <term>
4799       <envar>MOSUFFIX</envar>
4800     </term>
4801     <listitem><para>
4802 Suffix used for <literal>MO</literal> files (default: <literal>'.mo'</literal>).
4803 See &t-link-msgfmt; tool and &b-link-MOFiles; builder.
4804 </para>
4805 </listitem>
4806   </varlistentry>
4807   <varlistentry id="cv-MSGFMT">
4808     <term>
4809       <envar>MSGFMT</envar>
4810     </term>
4811     <listitem><para>
4812 Absolute path to <command>msgfmt(1)</command> binary, found by
4813 <function>Detect()</function>.
4814 See &t-link-msgfmt; tool and &b-link-MOFiles; builder.
4815 </para>
4816 </listitem>
4817   </varlistentry>
4818   <varlistentry id="cv-MSGFMTCOM">
4819     <term>
4820       <envar>MSGFMTCOM</envar>
4821     </term>
4822     <listitem><para>
4823 Complete command line to run <command>msgfmt(1)</command> program.
4824 See &t-link-msgfmt; tool and &b-link-MOFiles; builder.
4825 </para>
4826 </listitem>
4827   </varlistentry>
4828   <varlistentry id="cv-MSGFMTCOMSTR">
4829     <term>
4830       <envar>MSGFMTCOMSTR</envar>
4831     </term>
4832     <listitem><para>
4833 String to display when <command>msgfmt(1)</command> is invoked
4834 (default: <literal>''</literal>, which means ``print &cv-link-MSGFMTCOM;'').
4835 See &t-link-msgfmt; tool and &b-link-MOFiles; builder.
4836 </para>
4837 </listitem>
4838   </varlistentry>
4839   <varlistentry id="cv-MSGFMTFLAGS">
4840     <term>
4841       <envar>MSGFMTFLAGS</envar>
4842     </term>
4843     <listitem><para>
4844 Additional flags to <command>msgfmt(1)</command>.
4845 See &t-link-msgfmt; tool and &b-link-MOFiles; builder.
4846 </para>
4847 </listitem>
4848   </varlistentry>
4849   <varlistentry id="cv-MSGINIT">
4850     <term>
4851       <envar>MSGINIT</envar>
4852     </term>
4853     <listitem><para>
4854 Path to <command>msginit(1)</command> program (found via
4855 <literal>Detect()</literal>).
4856 See &t-link-msginit; tool and &b-link-POInit; builder.
4857 </para>
4858 </listitem>
4859   </varlistentry>
4860   <varlistentry id="cv-MSGINITCOM">
4861     <term>
4862       <envar>MSGINITCOM</envar>
4863     </term>
4864     <listitem><para>
4865 Complete command line to run <command>msginit(1)</command> program.
4866 See &t-link-msginit; tool and &b-link-POInit; builder.
4867 </para>
4868 </listitem>
4869   </varlistentry>
4870   <varlistentry id="cv-MSGINITCOMSTR">
4871     <term>
4872       <envar>MSGINITCOMSTR</envar>
4873     </term>
4874     <listitem><para>
4875 String to display when <command>msginit(1)</command> is invoked
4876 (default: <literal>''</literal>, which means ``print &cv-link-MSGINITCOM;'').
4877 See &t-link-msginit; tool and &b-link-POInit; builder.
4878 </para>
4879 </listitem>
4880   </varlistentry>
4881   <varlistentry id="cv-MSGINITFLAGS">
4882     <term>
4883       <envar>MSGINITFLAGS</envar>
4884     </term>
4885     <listitem><para>
4886 List of additional flags to <command>msginit(1)</command> (default:
4887 <literal>[]</literal>).
4888 See &t-link-msginit; tool and &b-link-POInit; builder.
4889 </para>
4890 </listitem>
4891   </varlistentry>
4892   <varlistentry id="cv-_MSGINITLOCALE">
4893     <term>
4894       <envar>_MSGINITLOCALE</envar>
4895     </term>
4896     <listitem><para>
4897 Internal ``macro''. Computes locale (language) name based on target filename
4898 (default: <literal>'${TARGET.filebase}' </literal>).
4899 </para>
4900 <para>
4901 See &t-link-msginit; tool and &b-link-POInit; builder.
4902 </para>
4903 </listitem>
4904   </varlistentry>
4905   <varlistentry id="cv-MSGMERGE">
4906     <term>
4907       <envar>MSGMERGE</envar>
4908     </term>
4909     <listitem><para>
4910 Absolute path to <command>msgmerge(1)</command> binary as found by
4911 <function>Detect()</function>.
4912 See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
4913 </para>
4914 </listitem>
4915   </varlistentry>
4916   <varlistentry id="cv-MSGMERGECOM">
4917     <term>
4918       <envar>MSGMERGECOM</envar>
4919     </term>
4920     <listitem><para>
4921 Complete command line to run <command>msgmerge(1)</command> command.
4922 See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
4923 </para>
4924 </listitem>
4925   </varlistentry>
4926   <varlistentry id="cv-MSGMERGECOMSTR">
4927     <term>
4928       <envar>MSGMERGECOMSTR</envar>
4929     </term>
4930     <listitem><para>
4931 String to be displayed when <command>msgmerge(1)</command> is invoked
4932 (default: <literal>''</literal>, which means ``print &cv-link-MSGMERGECOM;'').
4933 See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
4934 </para>
4935 </listitem>
4936   </varlistentry>
4937   <varlistentry id="cv-MSGMERGEFLAGS">
4938     <term>
4939       <envar>MSGMERGEFLAGS</envar>
4940     </term>
4941     <listitem><para>
4942 Additional flags to <command>msgmerge(1)</command> command.
4943 See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
4944 </para>
4945 </listitem>
4946   </varlistentry>
4947   <varlistentry id="cv-MSSDK_DIR">
4948     <term>
4949       <envar>MSSDK_DIR</envar>
4950     </term>
4951     <listitem><para>
4952 The directory containing the Microsoft SDK
4953 (either Platform SDK or Windows SDK)
4954 to be used for compilation.
4955 </para>
4956 </listitem>
4957   </varlistentry>
4958   <varlistentry id="cv-MSSDK_VERSION">
4959     <term>
4960       <envar>MSSDK_VERSION</envar>
4961     </term>
4962     <listitem><para>
4963 The version string of the Microsoft SDK
4964 (either Platform SDK or Windows SDK)
4965 to be used for compilation.
4966 Supported versions include
4967 <literal>6.1</literal>,
4968 <literal>6.0A</literal>,
4969 <literal>6.0</literal>,
4970 <literal>2003R2</literal>
4971 and
4972 <literal>2003R1</literal>.
4973 </para>
4974 </listitem>
4975   </varlistentry>
4976   <varlistentry id="cv-MSVC_BATCH">
4977     <term>
4978       <envar>MSVC_BATCH</envar>
4979     </term>
4980     <listitem><para>
4981 When set to any true value,
4982 specifies that &SCons; should batch
4983 compilation of object files
4984 when calling the &MSVC; compiler.
4985 All compilations of source files from the same source directory
4986 that generate target files in a same output directory
4987 and were configured in &SCons; using the same &consenv;
4988 will be built in a single call to the compiler.
4989 Only source files that have changed since their
4990 object files were built will be passed to each compiler invocation
4991 (via the &cv-link-CHANGED_SOURCES; &consvar;).
4992 Any compilations where the object (target) file base name
4993 (minus the <filename>.obj</filename>)
4994 does not match the source file base name
4995 will be compiled separately.
4996 </para>
4997 </listitem>
4998   </varlistentry>
4999   <varlistentry id="cv-MSVC_NOTFOUND_POLICY">
5000     <term>
5001       <envar>MSVC_NOTFOUND_POLICY</envar>
5002     </term>
5003     <listitem><para>
5004 Specify the &scons; behavior when the &MSVC; compiler is not detected.
5005 </para>
5006
5007 <para>
5008     The &cv-MSVC_NOTFOUND_POLICY; specifies the &scons; behavior when no msvc versions are detected or
5009     when the requested msvc version is not detected.
5010 </para>
5011
5012 <para>
5013 The valid values for &cv-MSVC_NOTFOUND_POLICY; and the corresponding &scons; behavior are:
5014 </para>
5015
5016 <variablelist>
5017
5018 <varlistentry>
5019 <term><parameter>'Error' or 'Exception'</parameter></term>
5020 <listitem>
5021 <para>
5022 Raise an exception when no msvc versions are detected or when the requested msvc version is not detected.
5023 </para>
5024 </listitem>
5025 </varlistentry>
5026
5027 <varlistentry>
5028 <term><parameter>'Warning' or 'Warn'</parameter></term>
5029 <listitem>
5030 <para>
5031 Issue a warning and continue when no msvc versions are detected or when the requested msvc version is not detected.
5032 Depending on usage, this could result in build failure(s).
5033 </para>
5034 </listitem>
5035 </varlistentry>
5036
5037 <varlistentry>
5038 <term><parameter>'Ignore' or 'Suppress'</parameter></term>
5039 <listitem>
5040 <para>
5041 Take no action and continue when no msvc versions are detected or when the requested msvc version is not detected.
5042 Depending on usage, this could result in build failure(s).
5043 </para>
5044 </listitem>
5045 </varlistentry>
5046
5047 </variablelist>
5048
5049 <para>
5050 Note: in addition to the camel case values shown above, lower case and upper case values are accepted as well.
5051 </para>
5052
5053 <para>
5054 The &cv-MSVC_NOTFOUND_POLICY; is applied when any of the following conditions are satisfied:
5055 <itemizedlist>
5056 <listitem><para>
5057 &cv-MSVC_VERSION; is specified, the default tools list is implicitly defined (i.e., the tools list is not specified),
5058 and the default tools list contains one or more of the msvc tools.
5059 </para></listitem>
5060 <listitem><para>
5061 &cv-MSVC_VERSION; is specified, the default tools list is explicitly specified (e.g., <literal>tools=['default']</literal>),
5062 and the default tools list contains one or more of the msvc tools.
5063 </para></listitem>
5064 <listitem><para>
5065 A non-default tools list is specified that contains one or more of the msvc tools (e.g., <literal>tools=['msvc', 'mslink']</literal>).
5066 </para></listitem>
5067 </itemizedlist>
5068 </para>
5069
5070 <para>
5071 The &cv-MSVC_NOTFOUND_POLICY; is ignored when any of the following conditions are satisfied:
5072 <itemizedlist>
5073 <listitem><para>
5074 &cv-MSVC_VERSION; is not specified and the default tools list is implicitly defined (i.e., the tools list is not specified).
5075 </para></listitem>
5076 <listitem><para>
5077 &cv-MSVC_VERSION; is not specified and the default tools list is explicitly specified (e.g., <literal>tools=['default']</literal>).
5078 </para></listitem>
5079 <listitem><para>
5080 A non-default tool list is specified that does not contain any of the msvc tools (e.g., <literal>tools=['mingw']</literal>).
5081 </para></listitem>
5082 </itemizedlist>
5083 </para>
5084
5085 <para>
5086 Important usage details:
5087 <itemizedlist>
5088
5089 <listitem><para>
5090 &cv-MSVC_NOTFOUND_POLICY; must be passed as an argument to the &f-link-Environment;
5091 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
5092 loaded via the default tools list or via a tools list passed to the
5093 &f-link-Environment; constructor.
5094 Otherwise, &cv-MSVC_NOTFOUND_POLICY; must be set before the first msvc tool is
5095 loaded into the environment.
5096 </para></listitem>
5097
5098 </itemizedlist>
5099 </para>
5100
5101 <para>
5102 When &cv-MSVC_NOTFOUND_POLICY; is not specified, the default &scons; behavior is to issue a warning and continue
5103 subject to the conditions listed above. The default &scons; behavior may change in the future.
5104 </para>
5105
5106 <para><emphasis>New in version 4.4</emphasis></para>
5107
5108 </listitem>
5109   </varlistentry>
5110   <varlistentry id="cv-MSVC_SCRIPT_ARGS">
5111     <term>
5112       <envar>MSVC_SCRIPT_ARGS</envar>
5113     </term>
5114     <listitem><para>
5115 Pass user-defined arguments to the &MSVC; batch file determined via autodetection.
5116 </para>
5117
5118 <para>
5119 &cv-MSVC_SCRIPT_ARGS; is available for msvc batch file arguments that do not have first-class support
5120 via &consvars; or when there is an issue with the appropriate &consvar; validation.
5121 When available, it is recommended to use the appropriate &consvars; (e.g., &cv-link-MSVC_TOOLSET_VERSION;)
5122 rather than &cv-MSVC_SCRIPT_ARGS; arguments.
5123 </para>
5124
5125 <para>
5126 The valid values for &cv-MSVC_SCRIPT_ARGS; are: <literal>None</literal>, a string,
5127 or a list of strings.
5128 </para>
5129
5130 <para>
5131 The &cv-MSVC_SCRIPT_ARGS; value is converted to a scalar string (i.e., "flattened").
5132 The resulting scalar string, if not empty, is passed as an argument to the msvc batch file determined
5133 via autodetection subject to the validation conditions listed below.
5134 </para>
5135
5136 <para>
5137 &cv-MSVC_SCRIPT_ARGS; is ignored when the value is <literal>None</literal> and when the
5138 result from argument conversion is an empty string.  The validation conditions below do not apply.
5139 </para>
5140
5141 <para>
5142 An exception is raised when any of the following conditions are satisfied:
5143 <itemizedlist>
5144
5145 <listitem><para>
5146 &cv-MSVC_SCRIPT_ARGS; is specified for Visual Studio 2013 and earlier.
5147 </para></listitem>
5148
5149 <listitem><para>
5150 Multiple SDK version arguments (e.g., <literal>'10.0.20348.0'</literal>) are specified
5151 in &cv-MSVC_SCRIPT_ARGS;.
5152 </para></listitem>
5153
5154 <listitem><para>
5155 &cv-link-MSVC_SDK_VERSION; is specified and an SDK version argument
5156 (e.g., <literal>'10.0.20348.0'</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;.
5157 Multiple SDK version declarations via &cv-link-MSVC_SDK_VERSION; and &cv-MSVC_SCRIPT_ARGS;
5158 are not allowed.
5159 </para></listitem>
5160
5161 <listitem><para>
5162 Multiple toolset version arguments (e.g., <literal>'-vcvars_ver=14.29'</literal>)
5163 are specified in &cv-MSVC_SCRIPT_ARGS;.
5164 </para></listitem>
5165
5166 <listitem><para>
5167 &cv-link-MSVC_TOOLSET_VERSION; is specified and a toolset version argument
5168 (e.g., <literal>'-vcvars_ver=14.29'</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;.
5169 Multiple toolset version declarations via &cv-link-MSVC_TOOLSET_VERSION; and
5170 &cv-MSVC_SCRIPT_ARGS; are not allowed.
5171 </para></listitem>
5172
5173 <listitem><para>
5174 Multiple spectre library arguments (e.g., <literal>'-vcvars_spectre_libs=spectre'</literal>)
5175 are specified in &cv-MSVC_SCRIPT_ARGS;.
5176 </para></listitem>
5177
5178 <listitem><para>
5179 &cv-link-MSVC_SPECTRE_LIBS; is enabled and a spectre library argument
5180 (e.g., <literal>'-vcvars_spectre_libs=spectre'</literal>) is specified in
5181 &cv-MSVC_SCRIPT_ARGS;. Multiple spectre library declarations via &cv-link-MSVC_SPECTRE_LIBS;
5182 and &cv-MSVC_SCRIPT_ARGS; are not allowed.
5183 </para></listitem>
5184
5185 <listitem><para>
5186 Multiple UWP arguments (e.g., <literal>uwp</literal> or <literal>store</literal>) are specified
5187 in &cv-MSVC_SCRIPT_ARGS;.
5188 </para></listitem>
5189
5190 <listitem><para>
5191 &cv-link-MSVC_UWP_APP; is enabled and a UWP argument (e.g., <literal>uwp</literal> or
5192 <literal>store</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;. Multiple UWP declarations
5193 via &cv-link-MSVC_UWP_APP; and &cv-MSVC_SCRIPT_ARGS; are not allowed.
5194 </para></listitem>
5195
5196 </itemizedlist>
5197 </para>
5198
5199 <para>
5200 Example 1 - A Visual Studio 2022 build with an SDK version and a toolset version
5201 specified with a string argument:
5202 <example_commands>
5203 env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS='10.0.20348.0 -vcvars_ver=14.29.30133')
5204 </example_commands>
5205 </para>
5206
5207 <para>
5208 Example 2 - A Visual Studio 2022 build with an SDK version and a toolset version
5209 specified with a list argument:
5210 <example_commands>
5211 env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['10.0.20348.0', '-vcvars_ver=14.29.30133'])
5212 </example_commands>
5213 </para>
5214
5215 <para>
5216 Important usage details:
5217 <itemizedlist>
5218
5219 <listitem><para>
5220 &cv-MSVC_SCRIPT_ARGS; must be passed as an argument to the &f-link-Environment;
5221 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
5222 loaded via the default tools list or via a tools list passed to the
5223 &f-link-Environment; constructor.
5224 Otherwise, &cv-MSVC_SCRIPT_ARGS; must be set before the first msvc tool is
5225 loaded into the environment.
5226 </para></listitem>
5227
5228 <listitem><para>
5229 Other than checking for multiple declarations as described above, &cv-MSVC_SCRIPT_ARGS; arguments
5230 are not validated.
5231 </para></listitem>
5232
5233 <listitem><para>
5234 <emphasis>
5235 Erroneous, inconsistent, and/or version incompatible &cv-MSVC_SCRIPT_ARGS; arguments are likely
5236 to result in build failures for reasons that are not readily apparent and may be difficult to diagnose.
5237 </emphasis>
5238 The burden is on the user to ensure that the arguments provided to the msvc batch file are valid, consistent
5239 and compatible with the version of msvc selected.
5240 </para></listitem>
5241
5242 </itemizedlist>
5243 </para>
5244
5245 <para><emphasis>New in version 4.4</emphasis></para>
5246
5247 </listitem>
5248   </varlistentry>
5249   <varlistentry id="cv-MSVC_SCRIPTERROR_POLICY">
5250     <term>
5251       <envar>MSVC_SCRIPTERROR_POLICY</envar>
5252     </term>
5253     <listitem><para>
5254 Specify the &scons; behavior when &MSVC; batch file errors are detected.
5255 </para>
5256
5257 <para>
5258 The &cv-MSVC_SCRIPTERROR_POLICY; specifies the &scons; behavior when msvc batch file errors are
5259 detected.
5260 When &cv-MSVC_SCRIPTERROR_POLICY; is not specified, the default &scons; behavior is to suppress
5261 msvc batch file error messages.
5262 </para>
5263 <para>
5264 The root cause of msvc build failures may be difficult to diagnose. In these situations, setting
5265 the &scons; behavior to issue a warning when msvc batch file errors are detected <emphasis>may</emphasis>
5266 produce additional diagnostic information.
5267 </para>
5268
5269 <para>
5270 The valid values for &cv-MSVC_SCRIPTERROR_POLICY; and the corresponding &scons; behavior are:
5271 </para>
5272
5273 <variablelist>
5274
5275 <varlistentry>
5276 <term><parameter>'Error' or 'Exception'</parameter></term>
5277 <listitem>
5278 <para>
5279 Raise an exception when msvc batch file errors are detected.
5280 </para>
5281 </listitem>
5282 </varlistentry>
5283
5284 <varlistentry>
5285 <term><parameter>'Warning' or 'Warn'</parameter></term>
5286 <listitem>
5287 <para>
5288 Issue a warning when msvc batch file errors are detected.
5289 </para>
5290 </listitem>
5291 </varlistentry>
5292
5293 <varlistentry>
5294 <term><parameter>'Ignore' or 'Suppress'</parameter></term>
5295 <listitem>
5296 <para>
5297 Suppress msvc batch file error messages.
5298 </para>
5299
5300 <para><emphasis>New in version 4.4</emphasis></para>
5301
5302 </listitem>
5303 </varlistentry>
5304
5305 </variablelist>
5306
5307 <para>
5308 Note: in addition to the camel case values shown above, lower case and upper case values are accepted as well.
5309 </para>
5310
5311 <para>
5312 Example 1 - A Visual Studio 2022 build with user-defined script arguments:
5313 <example_commands>
5314 env = environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['8.1', 'store', '-vcvars_ver=14.1'])
5315 env.Program('hello', ['hello.c'], CCFLAGS='/MD', LIBS=['kernel32', 'user32', 'runtimeobject'])
5316 </example_commands>
5317 </para>
5318
5319 <para>
5320 Example 1 - Output fragment:
5321 <example_commands>
5322 ...
5323 link /nologo /OUT:_build001\hello.exe kernel32.lib user32.lib runtimeobject.lib _build001\hello.obj
5324 LINK : fatal error LNK1104: cannot open file 'MSVCRT.lib'
5325 ...
5326 </example_commands>
5327 </para>
5328
5329 <para>
5330 Example 2 - A Visual Studio 2022 build with user-defined script arguments and the script error policy set
5331 to issue a warning when msvc batch file errors are detected:
5332 <example_commands>
5333 env = environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['8.1', 'store', '-vcvars_ver=14.1'], MSVC_SCRIPTERROR_POLICY='warn')
5334 env.Program('hello', ['hello.c'], CCFLAGS='/MD', LIBS=['kernel32', 'user32', 'runtimeobject'])
5335 </example_commands>
5336 </para>
5337
5338 <para>
5339 Example 2 - Output fragment:
5340 <example_commands>
5341 ...
5342 scons: warning: vc script errors detected:
5343 [ERROR:vcvars.bat] The UWP Application Platform requires a Windows 10 SDK.
5344 [ERROR:vcvars.bat] WindowsSdkDir = "C:\Program Files (x86)\Windows Kits\8.1\"
5345 [ERROR:vcvars.bat] host/target architecture is not supported : { x64 , x64 }
5346 ...
5347 link /nologo /OUT:_build001\hello.exe kernel32.lib user32.lib runtimeobject.lib _build001\hello.obj
5348 LINK : fatal error LNK1104: cannot open file 'MSVCRT.lib'
5349 </example_commands>
5350 </para>
5351
5352 <para>
5353 Important usage details:
5354 <itemizedlist>
5355
5356 <listitem><para>
5357 &cv-MSVC_SCRIPTERROR_POLICY; must be passed as an argument to the &f-link-Environment;
5358 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
5359 loaded via the default tools list or via a tools list passed to the
5360 &f-link-Environment; constructor.
5361 Otherwise, &cv-MSVC_SCRIPTERROR_POLICY; must be set before the first msvc tool is
5362 loaded into the environment.
5363 </para></listitem>
5364
5365 <listitem><para>
5366 Due to &scons; implementation details, not all Windows system environment variables are propagated
5367 to the environment in which the msvc batch file is executed.  Depending on Visual Studio version
5368 and installation options, non-fatal msvc batch file error messages may be generated for ancillary
5369 tools which may not affect builds with the msvc compiler.  For this reason, caution is recommended
5370 when setting the script error policy to raise an exception (e.g., <literal>'Error'</literal>).
5371 </para></listitem>
5372
5373 </itemizedlist>
5374 </para>
5375
5376 <para><emphasis>New in version 4.4</emphasis></para>
5377
5378 </listitem>
5379   </varlistentry>
5380   <varlistentry id="cv-MSVC_SDK_VERSION">
5381     <term>
5382       <envar>MSVC_SDK_VERSION</envar>
5383     </term>
5384     <listitem><para>
5385 Build with a specific version of the Microsoft Software Development Kit (SDK).
5386 </para>
5387
5388 <para>
5389 The valid values for &cv-MSVC_SDK_VERSION; are: <literal>None</literal>
5390 or a string containing the requested SDK version (e.g., <literal>'10.0.20348.0'</literal>).
5391 </para>
5392
5393 <para>
5394 &cv-MSVC_SDK_VERSION; is ignored when the value is <literal>None</literal> and when
5395 the value is an empty string.  The validation conditions below do not apply.
5396 </para>
5397
5398 <para>
5399 An exception is raised when any of the following conditions are satisfied:
5400 <itemizedlist>
5401
5402 <listitem><para>
5403 &cv-MSVC_SDK_VERSION; is specified for Visual Studio 2013 and earlier.
5404 </para></listitem>
5405
5406 <listitem><para>
5407 &cv-MSVC_SDK_VERSION; is specified and an SDK version argument is specified in
5408 &cv-link-MSVC_SCRIPT_ARGS;. Multiple SDK version declarations via &cv-MSVC_SDK_VERSION;
5409 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
5410 </para></listitem>
5411
5412 <listitem><para>
5413 The &cv-MSVC_SDK_VERSION; specified does not match any of the supported formats:
5414 <itemizedlist>
5415 <listitem><para>
5416 <literal>'10.0.XXXXX.Y'</literal> [SDK 10.0]
5417 </para></listitem>
5418 <listitem><para>
5419 <literal>'8.1'</literal> [SDK 8.1]
5420 </para></listitem>
5421 </itemizedlist>
5422 </para></listitem>
5423
5424 <listitem><para>
5425 The system folder for the corresponding &cv-MSVC_SDK_VERSION; version is not found.
5426 The requested SDK version does not appear to be installed.
5427 </para></listitem>
5428
5429 <listitem><para>
5430 The &cv-MSVC_SDK_VERSION; version does not appear to support the requested platform
5431 type (i.e., <literal>UWP</literal> or <literal>Desktop</literal>).  The requested SDK version
5432 platform type components do not appear to be installed.
5433 </para></listitem>
5434
5435 <listitem><para>
5436 The &cv-MSVC_SDK_VERSION; version is <literal>8.1</literal>, the platform type is
5437 <literal>UWP</literal>, and the build tools selected are from Visual Studio 2017
5438 and later (i.e., &cv-link-MSVC_VERSION; must be '14.0' or &cv-link-MSVC_TOOLSET_VERSION;
5439 must be '14.0').
5440 </para></listitem>
5441
5442 </itemizedlist>
5443 </para>
5444
5445 <para>
5446 Example 1 - A Visual Studio 2022 build with a specific Windows SDK version:
5447 <example_commands>
5448 env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.20348.0')
5449 </example_commands>
5450 </para>
5451
5452 <para>
5453 Example 2 - A Visual Studio 2022 build with a specific SDK version for the Universal Windows Platform:
5454 <example_commands>
5455 env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.20348.0', MSVC_UWP_APP=True)
5456 </example_commands>
5457 </para>
5458
5459 <para>
5460 Important usage details:
5461 <itemizedlist>
5462
5463 <listitem><para>
5464 &cv-MSVC_SDK_VERSION; must be passed as an argument to the &f-link-Environment;
5465 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
5466 loaded via the default tools list or via a tools list passed to the
5467 &f-link-Environment; constructor.
5468 Otherwise, &cv-MSVC_SDK_VERSION; must be set before the first msvc tool is
5469 loaded into the environment.
5470 </para></listitem>
5471
5472 <listitem>
5473 <para><emphasis>
5474 Should a SDK 10.0 version be installed that does not follow the naming scheme above, the
5475 SDK version will need to be specified via &cv-link-MSVC_SCRIPT_ARGS; until the version number
5476 validation format can be extended.
5477 </emphasis></para>
5478 </listitem>
5479
5480 <listitem><para>
5481 Should an exception be raised indicating that the SDK version is not found, verify that
5482 the requested SDK version is installed with the necessary platform type components.
5483 </para></listitem>
5484
5485 <listitem><para>
5486 There is a known issue with the Microsoft libraries when the target architecture is
5487 <literal>ARM64</literal> and a Windows 11 SDK (version <literal>'10.0.22000.0'</literal> and later) is used
5488 with the <literal>v141</literal> build tools and older <literal>v142</literal> toolsets
5489 (versions <literal>'14.28.29333'</literal> and earlier). Should build failures arise with these combinations
5490 of settings due to unresolved symbols in the Microsoft libraries, &cv-MSVC_SDK_VERSION; may be employed to
5491 specify a Windows 10 SDK (e.g., <literal>'10.0.20348.0'</literal>) for the build.
5492 </para></listitem>
5493
5494 </itemizedlist>
5495 </para>
5496
5497 <para><emphasis>New in version 4.4</emphasis></para>
5498
5499 </listitem>
5500   </varlistentry>
5501   <varlistentry id="cv-MSVC_SPECTRE_LIBS">
5502     <term>
5503       <envar>MSVC_SPECTRE_LIBS</envar>
5504     </term>
5505     <listitem><para>
5506 Build with the spectre-mitigated &MSVC; libraries.
5507 </para>
5508
5509 <para>
5510 The valid values for &cv-MSVC_SPECTRE_LIBS; are: <literal>True</literal>,
5511 <literal>False</literal>, or <literal>None</literal>.
5512 </para>
5513
5514 <para>
5515 When &cv-MSVC_SPECTRE_LIBS; is enabled (i.e., <literal>True</literal>),
5516 the &MSVC; environment will include the paths to the spectre-mitigated implementations
5517 of the &MSVC; libraries.
5518 </para>
5519
5520 <para>
5521 An exception is raised when any of the following conditions are satisfied:
5522 <itemizedlist>
5523
5524 <listitem><para>
5525 &cv-MSVC_SPECTRE_LIBS; is enabled for Visual Studio 2015 and earlier.
5526 </para></listitem>
5527
5528 <listitem><para>
5529 &cv-MSVC_SPECTRE_LIBS; is enabled and a spectre library argument is specified in
5530 &cv-link-MSVC_SCRIPT_ARGS;. Multiple spectre library declarations via &cv-MSVC_SPECTRE_LIBS;
5531 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
5532 </para></listitem>
5533
5534 <listitem><para>
5535 &cv-MSVC_SPECTRE_LIBS; is enabled and the platform type is <literal>UWP</literal>. There
5536 are no spectre-mitigated libraries for Universal Windows Platform (UWP) applications or
5537 components.
5538 </para></listitem>
5539
5540 </itemizedlist>
5541 </para>
5542
5543 <para>
5544 Example - A Visual Studio 2022 build with spectre mitigated &MSVC; libraries:
5545 <example_commands>
5546 env = Environment(MSVC_VERSION='14.3', MSVC_SPECTRE_LIBS=True)
5547 </example_commands>
5548 </para>
5549
5550 <para>
5551 Important usage details:
5552 <itemizedlist>
5553
5554 <listitem><para>
5555 &cv-MSVC_SPECTRE_LIBS; must be passed as an argument to the &f-link-Environment;
5556 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
5557 loaded via the default tools list or via a tools list passed to the
5558 &f-link-Environment; constructor.
5559 Otherwise, &cv-MSVC_SPECTRE_LIBS; must be set before the first msvc tool is
5560 loaded into the environment.
5561 </para></listitem>
5562
5563 <listitem><para>
5564 Additional compiler switches (e.g., <literal>/Qspectre</literal>) are necessary for including
5565 spectre mitigations when building user artifacts. Refer to the Visual Studio documentation for
5566 details.
5567 </para></listitem>
5568
5569 <listitem><para>
5570 <emphasis>
5571 The existence of the spectre libraries host architecture and target architecture folders are not
5572 verified when &cv-MSVC_SPECTRE_LIBS; is enabled which could result in build failures.
5573 </emphasis>
5574 The burden is on the user to ensure the requisite libraries with spectre mitigations are installed.
5575 </para></listitem>
5576
5577 </itemizedlist>
5578 </para>
5579
5580 <para><emphasis>New in version 4.4</emphasis></para>
5581
5582 </listitem>
5583   </varlistentry>
5584   <varlistentry id="cv-MSVC_TOOLSET_VERSION">
5585     <term>
5586       <envar>MSVC_TOOLSET_VERSION</envar>
5587     </term>
5588     <listitem><para>
5589 Build with a specific &MSVC; toolset version.
5590 </para>
5591
5592 <para><emphasis>
5593 Specifying &cv-MSVC_TOOLSET_VERSION; does not affect the autodetection and selection
5594 of msvc instances. The &cv-MSVC_TOOLSET_VERSION; is applied <emphasis>after</emphasis>
5595 an msvc instance is selected. This could be the default version of msvc if &cv-link-MSVC_VERSION;
5596 is not specified.
5597 </emphasis></para>
5598
5599 <para>
5600 The valid values for &cv-MSVC_TOOLSET_VERSION; are: <literal>None</literal>
5601 or a string containing the requested toolset version (e.g., <literal>'14.29'</literal>).
5602 </para>
5603
5604 <para>
5605 &cv-MSVC_TOOLSET_VERSION; is ignored when the value is <literal>None</literal> and when
5606 the value is an empty string.  The validation conditions below do not apply.
5607 </para>
5608
5609 <para>
5610 An exception is raised when any of the following conditions are satisfied:
5611 <itemizedlist>
5612
5613 <listitem><para>
5614 &cv-MSVC_TOOLSET_VERSION; is specified for Visual Studio 2015 and earlier.
5615 </para></listitem>
5616
5617 <listitem><para>
5618 &cv-MSVC_TOOLSET_VERSION; is specified and a toolset version argument is specified in
5619 &cv-link-MSVC_SCRIPT_ARGS;. Multiple toolset version declarations via &cv-MSVC_TOOLSET_VERSION;
5620 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
5621 </para></listitem>
5622
5623 <listitem>
5624 <para>
5625 The &cv-MSVC_TOOLSET_VERSION; specified does not match any of the supported formats:
5626 </para>
5627
5628 <itemizedlist>
5629
5630 <listitem><para>
5631 <literal>'XX.Y'</literal>
5632 </para></listitem>
5633
5634 <listitem><para>
5635 <literal>'XX.YY'</literal>
5636 </para></listitem>
5637
5638 <listitem><para>
5639 <literal>'XX.YY.ZZZZZ'</literal>
5640 </para></listitem>
5641
5642 <listitem><para>
5643 <literal>'XX.YY.Z'</literal> to <literal>'XX.YY.ZZZZ'</literal>
5644 <emphasis>
5645 [&scons; extension not directly supported by the msvc batch files and may be removed in the future]
5646 </emphasis>
5647 </para></listitem>
5648
5649 <listitem><para>
5650 <literal>'XX.YY.ZZ.N'</literal> [SxS format]
5651 </para></listitem>
5652
5653 <listitem><para>
5654 <literal>'XX.YY.ZZ.NN'</literal> [SxS format]
5655 </para></listitem>
5656
5657 </itemizedlist>
5658
5659 </listitem>
5660
5661 <listitem><para>
5662 The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the &cv-MSVC_TOOLSET_VERSION; specified
5663 is for Visual Studio 2013 and earlier (e.g., <literal>'12.0'</literal>).
5664 </para></listitem>
5665
5666 <listitem><para>
5667 The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the &cv-MSVC_TOOLSET_VERSION; specified
5668 is greater than the msvc version selected (e.g., <literal>'99.0'</literal>).
5669 </para></listitem>
5670
5671 <listitem><para>
5672 A system folder for the corresponding &cv-MSVC_TOOLSET_VERSION; version is not found.
5673 The requested toolset version does not appear to be installed.
5674 </para></listitem>
5675
5676 </itemizedlist>
5677 </para>
5678
5679 <para>
5680 Toolset selection details:
5681 <itemizedlist>
5682
5683 <listitem><para>
5684 When &cv-MSVC_TOOLSET_VERSION; is not an SxS version number or a full toolset version number:
5685 the first toolset version, ranked in descending order, that matches the &cv-MSVC_TOOLSET_VERSION;
5686 prefix is selected.
5687 </para></listitem>
5688
5689 <listitem><para>
5690 When &cv-MSVC_TOOLSET_VERSION; is specified using the major msvc version prefix
5691 (i.e., <literal>'XX.Y'</literal>) and the major msvc version is that of the latest release of
5692 Visual Studio, the selected toolset version may not be the same as the default &MSVC; toolset version.
5693 </para><para>
5694 In the latest release of Visual Studio, the default &MSVC; toolset version is not necessarily the
5695 toolset with the largest version number.
5696 </para></listitem>
5697
5698 </itemizedlist>
5699 </para>
5700
5701 <para>
5702 Example 1 - A default Visual Studio build with a partial toolset version specified:
5703 <example_commands>
5704 env = Environment(MSVC_TOOLSET_VERSION='14.2')
5705 </example_commands>
5706 </para>
5707
5708 <para>
5709 Example 2 - A default Visual Studio build with a partial toolset version specified:
5710 <example_commands>
5711 env = Environment(MSVC_TOOLSET_VERSION='14.29')
5712 </example_commands>
5713 </para>
5714
5715 <para>
5716 Example 3 - A Visual Studio 2022 build with a full toolset version specified:
5717 <example_commands>
5718 env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.29.30133')
5719 </example_commands>
5720 </para>
5721
5722 <para>
5723 Example 4 - A Visual Studio 2022 build with an SxS toolset version specified:
5724 <example_commands>
5725 env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.29.16.11')
5726 </example_commands>
5727 </para>
5728
5729 <para>
5730 Important usage details:
5731 <itemizedlist>
5732
5733 <listitem><para>
5734 &cv-MSVC_TOOLSET_VERSION; must be passed as an argument to the &f-link-Environment;
5735 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
5736 loaded via the default tools list or via a tools list passed to the
5737 &f-link-Environment; constructor.
5738 Otherwise, &cv-MSVC_TOOLSET_VERSION; must be set before the first msvc tool is
5739 loaded into the environment.
5740 </para></listitem>
5741
5742 <listitem><para>
5743 <emphasis>
5744 The existence of the toolset host architecture and target architecture folders are not verified
5745 when &cv-MSVC_TOOLSET_VERSION; is specified which could result in build failures.
5746 </emphasis>
5747 The burden is on the user to ensure the requisite toolset target architecture build tools are installed.
5748 </para></listitem>
5749
5750 </itemizedlist>
5751 </para>
5752
5753 <para><emphasis>New in version 4.4</emphasis></para>
5754
5755 </listitem>
5756   </varlistentry>
5757   <varlistentry id="cv-MSVC_USE_SCRIPT">
5758     <term>
5759       <envar>MSVC_USE_SCRIPT</envar>
5760     </term>
5761     <listitem><para>
5762 Use a batch script to set up the &MSVC; compiler.
5763 </para>
5764
5765 <para>
5766 If set to the name of a Visual Studio <filename>.bat</filename> file
5767 (e.g. <filename>vcvars.bat</filename>),
5768 &SCons; will run that batch file instead of the auto-detected one,
5769 and extract the relevant variables from the result (typically
5770 <envar>%INCLUDE%</envar>,
5771 <envar>%LIB%</envar>, and
5772 <envar>%PATH%</envar>) for supplying to the build.
5773 This can be useful to force the use of a compiler version that
5774 &SCons; does not detect.
5775 &cv-link-MSVC_USE_SCRIPT_ARGS; provides arguments passed to this script.
5776 </para>
5777
5778 <para>
5779 Setting
5780 &cv-MSVC_USE_SCRIPT; to <constant>None</constant> bypasses the
5781 Visual Studio autodetection entirely;
5782 use this if you are running &SCons; in a Visual Studio <command>cmd</command>
5783 window and importing the shell's environment variables - that
5784 is, if you are sure everything is set correctly already and
5785 you don't want &SCons; to change anything.
5786 </para>
5787 <para>
5788 &cv-MSVC_USE_SCRIPT; ignores &cv-link-MSVC_VERSION; and &cv-link-TARGET_ARCH;.
5789 </para>
5790
5791 <para><emphasis>Changed in version 4.4:</emphasis>
5792 new &cv-link-MSVC_USE_SCRIPT_ARGS; provides a
5793 way to pass arguments.
5794 </para>
5795
5796 </listitem>
5797   </varlistentry>
5798   <varlistentry id="cv-MSVC_USE_SCRIPT_ARGS">
5799     <term>
5800       <envar>MSVC_USE_SCRIPT_ARGS</envar>
5801     </term>
5802     <listitem><para>
5803 Provides arguments passed to the script &cv-link-MSVC_USE_SCRIPT;.
5804 </para>
5805
5806 <para><emphasis>New in version 4.4</emphasis></para>
5807
5808 </listitem>
5809   </varlistentry>
5810   <varlistentry id="cv-MSVC_USE_SETTINGS">
5811     <term>
5812       <envar>MSVC_USE_SETTINGS</envar>
5813     </term>
5814     <listitem><para>
5815 Use a dictionary to set up the &MSVC; compiler.
5816 </para>
5817
5818 <para>
5819 &cv-MSVC_USE_SETTINGS; is ignored when &cv-link-MSVC_USE_SCRIPT; is defined
5820 and/or when &cv-MSVC_USE_SETTINGS; is set to <constant>None</constant>.
5821 </para>
5822
5823 <para>
5824 The dictionary is used to populate the environment with the relevant variables
5825 (typically <envar>%INCLUDE%</envar>, <envar>%LIB%</envar>, and <envar>%PATH%</envar>)
5826 for supplying to the build. This can be useful to force the use of a compiler environment
5827 that &SCons; does not configure correctly. This is an alternative to manually configuring
5828 the environment when bypassing Visual Studio autodetection entirely by setting
5829 &cv-link-MSVC_USE_SCRIPT; to <constant>None</constant>.
5830 </para>
5831
5832 <para>
5833 Here is an example of configuring a build environment using the &MSVC; compiler
5834 included in the Microsoft SDK on a 64-bit host and building for a 64-bit architecture:
5835 <programlisting>
5836 # Microsoft SDK 6.0 (MSVC 8.0): 64-bit host and 64-bit target
5837 msvc_use_settings = {
5838     "PATH": [
5839         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Bin\\x64",
5840         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin\\x64",
5841         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin",
5842         "C:\\Windows\\Microsoft.NET\\Framework\\v2.0.50727",
5843         "C:\\Windows\\system32",
5844         "C:\\Windows",
5845         "C:\\Windows\\System32\\Wbem",
5846         "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\"
5847     ],
5848     "INCLUDE": [
5849         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Include",
5850         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Include\\Sys",
5851         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Include",
5852         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Include\\gl",
5853     ],
5854     "LIB": [
5855         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Lib\\x64",
5856         "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Lib\\x64",
5857     ],
5858     "LIBPATH": [],
5859     "VSCMD_ARG_app_plat": [],
5860     "VCINSTALLDIR": [],
5861     "VCToolsInstallDir": []
5862 }
5863
5864 # Specifying MSVC_VERSION is recommended
5865 env = Environment(MSVC_VERSION='8.0', MSVC_USE_SETTINGS=msvc_use_settings)
5866 </programlisting>
5867 </para>
5868
5869 <para>
5870 Important usage details:
5871 <itemizedlist>
5872
5873 <listitem><para>
5874 &cv-MSVC_USE_SETTINGS; must be passed as an argument to the &f-link-Environment;
5875 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
5876 loaded via the default tools list or via a tools list passed to the
5877 &f-link-Environment; constructor.
5878 Otherwise, &cv-MSVC_USE_SETTINGS; must be set before the first msvc tool is
5879 loaded into the environment.
5880 </para></listitem>
5881
5882 <listitem><para>
5883 <emphasis>
5884 The dictionary content requirements are based on the internal msvc implementation and
5885 therefore may change at any time.
5886 </emphasis>
5887 The burden is on the user to ensure the dictionary contents are minimally sufficient to
5888 ensure successful builds.
5889 </para>
5890
5891 </listitem>
5892
5893 </itemizedlist>
5894 </para>
5895
5896 <para><emphasis>New in version 4.4</emphasis></para>
5897
5898 </listitem>
5899   </varlistentry>
5900   <varlistentry id="cv-MSVC_UWP_APP">
5901     <term>
5902       <envar>MSVC_UWP_APP</envar>
5903     </term>
5904     <listitem><para>
5905 Build with the Universal Windows Platform (UWP) application &MSVC; libraries.
5906 </para>
5907
5908 <para>
5909 The valid values for &cv-MSVC_UWP_APP; are: <literal>True</literal>,
5910 <literal>'1'</literal>, <literal>False</literal>, <literal>'0'</literal>,
5911 or <literal>None</literal>.
5912 </para>
5913
5914 <para>
5915 When &cv-MSVC_UWP_APP; is enabled (i.e., <literal>True</literal> or
5916 <literal>'1'</literal>), the &MSVC; environment will be set up to point
5917 to the Windows Store compatible libraries and &MSVC; runtimes. In doing so,
5918 any libraries that are built will be able to be used in a UWP App and published
5919 to the Windows Store.
5920 <!-- This flag will only have an effect with Visual Studio 2015 or later. -->
5921 <!-- This variable must be passed as an argument to the Environment()
5922 constructor; setting it later has no effect. -->
5923 </para>
5924
5925 <para>
5926 An exception is raised when any of the following conditions are satisfied:
5927 <itemizedlist>
5928 <listitem><para>
5929 &cv-MSVC_UWP_APP; is enabled for Visual Studio 2013 and earlier.
5930 </para></listitem>
5931 <listitem><para>
5932 &cv-MSVC_UWP_APP; is enabled and a UWP argument is specified in
5933 &cv-link-MSVC_SCRIPT_ARGS;. Multiple UWP declarations via &cv-MSVC_UWP_APP;
5934 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
5935 </para></listitem>
5936 </itemizedlist>
5937 </para>
5938
5939 <para>
5940 Example - A Visual Studio 2022 build for the Universal Windows Platform:
5941 <example_commands>
5942 env = Environment(MSVC_VERSION='14.3', MSVC_UWP_APP=True)
5943 </example_commands>
5944 </para>
5945
5946 <para>
5947 Important usage details:
5948 <itemizedlist>
5949
5950 <listitem><para>
5951 &cv-MSVC_UWP_APP; must be passed as an argument to the &f-link-Environment;
5952 constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
5953 loaded via the default tools list or via a tools list passed to the
5954 &f-link-Environment; constructor.
5955 Otherwise, &cv-MSVC_UWP_APP; must be set before the first msvc tool is
5956 loaded into the environment.
5957 </para></listitem>
5958
5959 <listitem><para>
5960 <emphasis>
5961 The existence of the UWP libraries is not verified when &cv-MSVC_UWP_APP; is enabled
5962 which could result in build failures.
5963 </emphasis>
5964 The burden is on the user to ensure the requisite UWP libraries are installed.
5965 </para></listitem>
5966
5967 </itemizedlist>
5968 </para>
5969
5970 </listitem>
5971   </varlistentry>
5972   <varlistentry id="cv-MSVC_VERSION">
5973     <term>
5974       <envar>MSVC_VERSION</envar>
5975     </term>
5976     <listitem><para>
5977 A string to select the preferred  version of &MSVC;.
5978 If the specified version is unavailable and/or unknown to &SCons;,
5979 a warning is issued showing the versions actually discovered,
5980 and the build will eventually fail indicating a missing compiler binary.
5981 If &cv-MSVC_VERSION; is not set, &SCons; will (by default) select the
5982 latest version of &MSVC; installed on your system
5983 (excluding any preview versions).
5984 </para>
5985
5986 <note>
5987   <para>
5988     In order to take effect, &cv-MSVC_VERSION; must be set before
5989     the initial &MSVC; compiler discovery takes place.
5990     Discovery happens, at the latest, during the first call to the
5991     &f-link-Environment; function, unless a <parameter>tools</parameter>
5992     list is specified which excludes the entire &MSVC; toolchain -
5993     that is, omits <literal>"defaults"</literal>
5994     and any specific tool module that refers to parts of the toolchain
5995     (&t-link-msvc;, &t-link-mslink;, &t-link-masm;, &t-link-midl;
5996     and &t-link-msvs;). In this case, detection is deferred until
5997     any one of those tool modules is invoked manually.
5998     The following two examples illustrate this:
5999   </para>
6000
6001   <programlisting>
6002 # MSVC_VERSION set as Environment is created
6003 env = Environment(MSVC_VERSION='14.2')
6004
6005 # Initialization deferred with empty tools, triggered manually
6006 env = Environment(tools=[])
6007 env['MSVC_VERSION'] = '14.2
6008 env.Tool('msvc')
6009 env.Tool('mslink')
6010 env.Tool('msvs')
6011   </programlisting>
6012 </note>
6013
6014 <para>
6015 The valid values for &cv-MSVC_VERSION; represent major versions
6016 of the compiler, except that versions ending in <literal>Exp</literal>
6017 refer to "Express" or "Express for Desktop" Visual Studio editions.
6018 Values that do not look like a valid compiler version
6019 <emphasis>string</emphasis> are not supported.
6020 </para>
6021
6022 <para>
6023 The following table shows the correspondence
6024 of &cv-MSVC_VERSION; values to various version indicators
6025 ('x' is used as a placeholder for
6026 a single digit that can vary).
6027 </para>
6028
6029 <informaltable>
6030   <tgroup cols="5">
6031     <colspec align="left"/>
6032     <colspec align="center"/>
6033     <colspec align="center"/>
6034     <colspec align="left"/>
6035     <colspec align="center"/>
6036     <thead>
6037       <row>
6038         <entry> SCons Key </entry>
6039         <entry> <literallayout>
6040 Visual C++
6041 Version </literallayout></entry>
6042         <entry> <literal>_MSVC_VER</literal> </entry>
6043         <entry> Visual Studio Product </entry>
6044         <!--entry> <literallayout>
6045 Visual Studio
6046 Product </literallayout></entry-->
6047         <entry> <literallayout>
6048 MSBuild /
6049 Visual Studio </literallayout></entry>
6050       </row>
6051     </thead>
6052     <tbody>
6053       <row>
6054         <entry> <literal>"14.3"</literal> </entry>
6055         <entry> 14.3x </entry>
6056         <entry> 193x </entry>
6057         <entry> Visual Studio 2022 </entry>
6058         <entry> 17.x, 17.1x </entry>
6059       </row>
6060       <row>
6061         <entry> <literal>"14.2"</literal> </entry>
6062         <entry> 14.2x </entry>
6063         <entry> 192x </entry>
6064         <entry> Visual Studio 2019 </entry>
6065         <entry> 16.x, 16.1x </entry>
6066       </row>
6067       <row>
6068         <entry> <literal>"14.1"</literal> </entry>
6069         <entry> 14.1 or 14.1x </entry>
6070         <entry> 191x </entry>
6071         <entry> Visual Studio 2017 </entry>
6072         <entry> 15.x </entry>
6073       </row>
6074       <row>
6075         <entry> <literal>"14.1Exp"</literal> </entry>
6076         <entry> 14.1 or 14.1x </entry>
6077         <entry> 191x </entry>
6078         <entry> Visual Studio 2017 Express </entry>
6079         <entry> 15.x </entry>
6080       </row>
6081       <row>
6082         <entry> <literal>"14.0"</literal> </entry>
6083         <entry> 14.0 </entry>
6084         <entry> 1900 </entry>
6085         <entry> Visual Studio 2015 </entry>
6086         <entry> 14.0 </entry>
6087       </row>
6088       <row>
6089         <entry> <literal>"14.0Exp"</literal> </entry>
6090         <entry> 14.0 </entry>
6091         <entry> 1900 </entry>
6092         <entry> Visual Studio 2015 Express </entry>
6093         <entry> 14.0 </entry>
6094       </row>
6095       <row>
6096         <entry> <literal>"12.0"</literal> </entry>
6097         <entry> 12.0 </entry>
6098         <entry> 1800 </entry>
6099         <entry> Visual Studio 2013 </entry>
6100         <entry> 12.0 </entry>
6101       </row>
6102       <row>
6103         <entry> <literal>"12.0Exp"</literal> </entry>
6104         <entry> 12.0 </entry>
6105         <entry> 1800 </entry>
6106         <entry> Visual Studio 2013 Express </entry>
6107         <entry> 12.0 </entry>
6108       </row>
6109       <row>
6110         <entry> <literal>"11.0"</literal> </entry>
6111         <entry> 11.0 </entry>
6112         <entry> 1700 </entry>
6113         <entry> Visual Studio 2012 </entry>
6114         <entry> 11.0 </entry>
6115       </row>
6116       <row>
6117         <entry> <literal>"11.0Exp"</literal> </entry>
6118         <entry> 11.0 </entry>
6119         <entry> 1700 </entry>
6120         <entry> Visual Studio 2012 Express </entry>
6121         <entry> 11.0 </entry>
6122       </row>
6123       <row>
6124         <entry> <literal>"10.0"</literal> </entry>
6125         <entry> 10.0 </entry>
6126         <entry> 1600 </entry>
6127         <entry> Visual Studio 2010 </entry>
6128         <entry> 10.0 </entry>
6129       </row>
6130       <row>
6131         <entry> <literal>"10.0Exp"</literal> </entry>
6132         <entry> 10.0 </entry>
6133         <entry> 1600 </entry>
6134         <entry> Visual C++ Express 2010 </entry>
6135         <entry> 10.0 </entry>
6136       </row>
6137       <row>
6138         <entry> <literal>"9.0"</literal> </entry>
6139         <entry> 9.0 </entry>
6140         <entry> 1500 </entry>
6141         <entry> Visual Studio 2008 </entry>
6142         <entry> 9.0 </entry>
6143       </row>
6144       <row>
6145         <entry> <literal>"9.0Exp"</literal> </entry>
6146         <entry> 9.0 </entry>
6147         <entry> 1500 </entry>
6148         <entry> Visual C++ Express 2008 </entry>
6149         <entry> 9.0 </entry>
6150       </row>
6151       <row>
6152         <entry> <literal>"8.0"</literal> </entry>
6153         <entry> 8.0 </entry>
6154         <entry> 1400 </entry>
6155         <entry> Visual Studio 2005 </entry>
6156         <entry> 8.0 </entry>
6157       </row>
6158       <row>
6159         <entry> <literal>"8.0Exp"</literal> </entry>
6160         <entry> 8.0 </entry>
6161         <entry> 1400 </entry>
6162         <entry> Visual C++ Express 2005 </entry>
6163         <entry> 8.0 </entry>
6164       </row>
6165       <row>
6166         <entry> <literal>"7.1"</literal> </entry>
6167         <entry> 7.1 </entry>
6168         <entry> 1300 </entry>
6169         <entry> Visual Studio .NET 2003 </entry>
6170         <entry> 7.1 </entry>
6171       </row>
6172       <row>
6173         <entry> <literal>"7.0"</literal> </entry>
6174         <entry> 7.0 </entry>
6175         <entry> 1200 </entry>
6176         <entry> Visual Studio .NET 2002 </entry>
6177         <entry> 7.0 </entry>
6178       </row>
6179       <row>
6180         <entry> <literal>"6.0"</literal> </entry>
6181         <entry> 6.0 </entry>
6182         <entry> 1100 </entry>
6183         <entry> Visual Studio 6.0 </entry>
6184         <entry> 6.0 </entry>
6185       </row>
6186     </tbody>
6187   </tgroup>
6188 </informaltable>
6189
6190 <note>
6191   <itemizedlist>
6192
6193     <listitem><para>
6194     It is not necessary to install a Visual Studio IDE
6195     to build with &SCons; (for example, you can install only
6196     Build Tools), but when a Visual Studio IDE is installed,
6197     additional builders such as &b-link-MSVSSolution; and
6198     &b-link-MSVSProject; become available and correspond to
6199     the specified versions.
6200     </para></listitem>
6201
6202     <listitem><para>
6203     Versions ending in <literal>Exp</literal> refer to historical
6204     "Express" or "Express for Desktop" Visual Studio editions,
6205     which had feature limitations compared to the full editions.
6206     It is only necessary to specify the <literal>Exp</literal>
6207     suffix to select the express edition when both express and
6208     non-express editions of the same product are installed
6209     simulaneously. The <literal>Exp</literal> suffix is unnecessary,
6210     but accepted, when only the express edition is installed.
6211     </para></listitem>
6212   </itemizedlist>
6213 </note>
6214
6215 <para>
6216 The compilation environment can be further or more precisely specified through the
6217 use of several other &consvars;: see the descriptions of
6218 &cv-link-MSVC_TOOLSET_VERSION;,
6219 &cv-link-MSVC_SDK_VERSION;,
6220 &cv-link-MSVC_USE_SCRIPT;,
6221 &cv-link-MSVC_USE_SCRIPT_ARGS;,
6222 and &cv-link-MSVC_USE_SETTINGS;.
6223 </para>
6224
6225 </listitem>
6226   </varlistentry>
6227   <varlistentry id="cv-MSVS">
6228     <term>
6229       <envar>MSVS</envar>
6230     </term>
6231     <listitem><para>
6232         When the Microsoft Visual Studio tools are initialized,
6233         they set up this dictionary with the following keys:
6234       </para>
6235       <variablelist>
6236         <varlistentry>
6237           <term>VERSION</term>
6238           <listitem>
6239             <para>the version of MSVS being used (can be set via
6240             &cv-link-MSVC_VERSION;)</para>
6241           </listitem>
6242         </varlistentry>
6243         <varlistentry>
6244           <term>VERSIONS</term>
6245           <listitem>
6246             <para>the available versions of MSVS installed</para>
6247           </listitem>
6248         </varlistentry>
6249         <varlistentry>
6250           <term>VCINSTALLDIR</term>
6251           <listitem>
6252             <para>installed directory of &MSVC;</para>
6253           </listitem>
6254         </varlistentry>
6255         <varlistentry>
6256           <term>VSINSTALLDIR</term>
6257           <listitem>
6258             <para>installed directory of Visual Studio</para>
6259           </listitem>
6260         </varlistentry>
6261         <varlistentry>
6262           <term>FRAMEWORKDIR</term>
6263           <listitem>
6264             <para>installed directory of the .NET framework</para>
6265           </listitem>
6266         </varlistentry>
6267         <varlistentry>
6268           <term>FRAMEWORKVERSIONS</term>
6269           <listitem>
6270             <para>
6271               list of installed versions of the .NET framework,
6272               sorted latest to oldest.
6273             </para>
6274           </listitem>
6275         </varlistentry>
6276         <varlistentry>
6277           <term>FRAMEWORKVERSION</term>
6278           <listitem>
6279             <para>latest installed version of the .NET framework</para>
6280           </listitem>
6281         </varlistentry>
6282         <varlistentry>
6283           <term>FRAMEWORKSDKDIR</term>
6284           <listitem>
6285             <para>installed location of the .NET SDK.</para>
6286           </listitem>
6287         </varlistentry>
6288         <varlistentry>
6289           <term>PLATFORMSDKDIR</term>
6290           <listitem>
6291             <para>installed location of the Platform SDK.</para>
6292           </listitem>
6293         </varlistentry>
6294         <varlistentry>
6295           <term>PLATFORMSDK_MODULES</term>
6296           <listitem>
6297             <para>
6298               dictionary of installed Platform SDK modules, where the
6299               dictionary keys are keywords for the various modules,
6300               and the values are 2-tuples where the first is the
6301               release date, and the second is the version number.
6302             </para>
6303           </listitem>
6304         </varlistentry>
6305       </variablelist>
6306       <para>If a value is not set, it was not available in the registry.
6307       Visual Studio 2017 and later do not use the registry for
6308       primary storage of this information, so typically for these
6309       versions only  <literal>PROJECTSUFFIX</literal> and
6310       <literal>SOLUTIONSUFFIX</literal> will be set.
6311       </para>
6312     </listitem>
6313   </varlistentry>
6314   <varlistentry id="cv-MSVS_ARCH">
6315     <term>
6316       <envar>MSVS_ARCH</envar>
6317     </term>
6318     <listitem><para>Sets the architecture for which the generated project(s) should build.</para>
6319       <para>
6320         The default value is <literal>x86</literal>.
6321         <literal>amd64</literal> is also supported by &SCons; for
6322         most Visual Studio versions. Since Visual Studio 2015
6323         <literal>arm</literal> is supported, and since Visual Studio
6324         2017 <literal>arm64</literal> is supported.
6325         Trying to set &cv-MSVS_ARCH;
6326         to an architecture that's not supported for a given Visual
6327         Studio version will generate an error.
6328       </para>
6329     </listitem>
6330   </varlistentry>
6331   <varlistentry id="cv-MSVS_PROJECT_GUID">
6332     <term>
6333       <envar>MSVS_PROJECT_GUID</envar>
6334     </term>
6335     <listitem><para>
6336         The string placed in a generated
6337         &MSVC; project file as the value of the
6338         <literal>ProjectGUID</literal> attribute. There is no default
6339         value. If not defined, a new GUID is generated.
6340       </para>
6341     </listitem>
6342   </varlistentry>
6343   <varlistentry id="cv-MSVS_SCC_AUX_PATH">
6344     <term>
6345       <envar>MSVS_SCC_AUX_PATH</envar>
6346     </term>
6347     <listitem><para>
6348         The path name placed in a generated
6349         &MSVC; project file as the value of the
6350         <literal>SccAuxPath</literal> attribute if the
6351         <envar>MSVS_SCC_PROVIDER</envar> &consvar; is
6352         also set. There is no default value.
6353       </para>
6354     </listitem>
6355   </varlistentry>
6356   <varlistentry id="cv-MSVS_SCC_CONNECTION_ROOT">
6357     <term>
6358       <envar>MSVS_SCC_CONNECTION_ROOT</envar>
6359     </term>
6360     <listitem><para>
6361         The root path of projects in your SCC workspace, i.e the
6362         path under which all project and solution files will be
6363         generated. It is used as a reference path from which the
6364         relative paths of the generated &MSVC; project
6365         and solution files are computed. The relative project file path
6366         is placed as the value of the <literal>SccLocalPath</literal>
6367         attribute of the project file and as the values of the
6368         <literal>SccProjectFilePathRelativizedFromConnection[i]</literal>
6369         (where [i] ranges from 0 to the number of projects in the solution)
6370         attributes of the <literal>GlobalSection(SourceCodeControl)</literal>
6371         section of the Microsoft Visual Studio solution file. Similarly
6372         the relative solution file path is placed as the values of the
6373         <literal>SccLocalPath[i]</literal> (where [i] ranges from 0
6374         to the number of projects in the solution) attributes of the
6375         <literal>GlobalSection(SourceCodeControl)</literal> section of
6376         the Microsoft Visual Studio solution file. This is used only if
6377         the <envar>MSVS_SCC_PROVIDER</envar> &consvar; is
6378         also set. The default value is the current working directory.
6379       </para>
6380     </listitem>
6381   </varlistentry>
6382   <varlistentry id="cv-MSVS_SCC_PROJECT_NAME">
6383     <term>
6384       <envar>MSVS_SCC_PROJECT_NAME</envar>
6385     </term>
6386     <listitem><para>
6387         The project name placed in a generated &MSVC;
6388         project file as the value of the
6389         <literal>SccProjectName</literal> attribute if the
6390         <envar>MSVS_SCC_PROVIDER</envar> &consvar;
6391         is also set. In this case the string is also placed in
6392         the <literal>SccProjectName0</literal> attribute of the
6393         <literal>GlobalSection(SourceCodeControl)</literal> section
6394         of the Microsoft Visual Studio solution file. There is no
6395         default value.
6396       </para>
6397     </listitem>
6398   </varlistentry>
6399   <varlistentry id="cv-MSVS_SCC_PROVIDER">
6400     <term>
6401       <envar>MSVS_SCC_PROVIDER</envar>
6402     </term>
6403     <listitem><para>
6404         The string placed in a generated &MSVC;
6405         project file as the value of the
6406         <literal>SccProvider</literal> attribute. The string is
6407         also placed in the <literal>SccProvider0</literal> attribute
6408         of the <literal>GlobalSection(SourceCodeControl)</literal>
6409         section of the Microsoft Visual Studio solution file. There
6410         is no default value.
6411       </para>
6412     </listitem>
6413   </varlistentry>
6414   <varlistentry id="cv-MSVS_VERSION">
6415     <term>
6416       <envar>MSVS_VERSION</envar>
6417     </term>
6418     <listitem><para>Set the preferred version of Microsoft Visual Studio to use.</para>
6419       <para>
6420         If &cv-MSVS_VERSION; is not set, &SCons; will (by default)
6421         select the latest version of Visual Studio installed on your
6422         system. So, if you have version 6 and version 7 (MSVS .NET)
6423         installed, it will prefer version 7. You can override this by
6424         specifying the &cv-link-MSVS_VERSION; variable when
6425         initializing the Environment, setting it to the appropriate
6426         version ('6.0' or '7.0', for example). If the specified
6427         version isn't installed, tool initialization will fail.
6428       </para>
6429       <para>
6430         <emphasis>Deprecated since 1.3.0:</emphasis>
6431         &cv-MSVS_VERSION; is deprecated in favor of &cv-link-MSVC_VERSION;.
6432         As a transitional aid, if &cv-MSVS_VERSION; is set
6433         and &cv-MSVC_VERSION; is not,
6434         &cv-MSVC_VERSION; will be initialized to the value
6435         of &cv-MSVS_VERSION;.
6436         An error is raised if If both are set and have different values,
6437       </para>
6438     </listitem>
6439   </varlistentry>
6440   <varlistentry id="cv-MSVSBUILDCOM">
6441     <term>
6442       <envar>MSVSBUILDCOM</envar>
6443     </term>
6444     <listitem><para>
6445         The build command line placed in a generated &MSVC;
6446         project file. The default is to have Visual Studio
6447         invoke &SCons; with any specified build targets.
6448       </para>
6449     </listitem>
6450   </varlistentry>
6451   <varlistentry id="cv-MSVSCLEANCOM">
6452     <term>
6453       <envar>MSVSCLEANCOM</envar>
6454     </term>
6455     <listitem><para>
6456         The clean command line placed in a generated &MSVC;
6457         project file. The default is to have Visual Studio
6458         invoke &SCons; with the <option>-c</option> option to remove
6459         any specified targets.
6460       </para>
6461     </listitem>
6462   </varlistentry>
6463   <varlistentry id="cv-MSVSENCODING">
6464     <term>
6465       <envar>MSVSENCODING</envar>
6466     </term>
6467     <listitem><para>
6468         The encoding string placed in a generated &MSVC;
6469         project file. The default is encoding
6470         <literal>Windows-1252</literal>.
6471       </para>
6472     </listitem>
6473   </varlistentry>
6474   <varlistentry id="cv-MSVSPROJECTCOM">
6475     <term>
6476       <envar>MSVSPROJECTCOM</envar>
6477     </term>
6478     <listitem><para>The action used to generate &MSVC; project files.</para>
6479     </listitem>
6480   </varlistentry>
6481   <varlistentry id="cv-MSVSPROJECTSUFFIX">
6482     <term>
6483       <envar>MSVSPROJECTSUFFIX</envar>
6484     </term>
6485     <listitem><para>
6486         The suffix used for &MSVC; project (DSP)
6487         files. The default value is
6488         <filename>.vcxproj</filename> when using Visual Studio 2010
6489         and later, <filename>.vcproj</filename>
6490         when using Visual Studio versions between 2002 and 2008,
6491         and <filename>.dsp</filename> when using Visual Studio 6.0.
6492       </para>
6493     </listitem>
6494   </varlistentry>
6495   <varlistentry id="cv-MSVSREBUILDCOM">
6496     <term>
6497       <envar>MSVSREBUILDCOM</envar>
6498     </term>
6499     <listitem><para>
6500         The rebuild command line placed in a generated &MSVC;
6501         project file. The default is to have Visual
6502         Studio invoke &SCons; with any specified rebuild targets.
6503
6504       </para>
6505     </listitem>
6506   </varlistentry>
6507   <varlistentry id="cv-MSVSSCONS">
6508     <term>
6509       <envar>MSVSSCONS</envar>
6510     </term>
6511     <listitem><para>
6512         The &SCons; used in generated &MSVC; project
6513         files. The default is the version of &SCons; being used to
6514         generate the project file.
6515       </para>
6516     </listitem>
6517   </varlistentry>
6518   <varlistentry id="cv-MSVSSCONSCOM">
6519     <term>
6520       <envar>MSVSSCONSCOM</envar>
6521     </term>
6522     <listitem><para>
6523         The default &SCons; command used in generated &MSVC; project files.
6524       </para>
6525     </listitem>
6526   </varlistentry>
6527   <varlistentry id="cv-MSVSSCONSCRIPT">
6528     <term>
6529       <envar>MSVSSCONSCRIPT</envar>
6530     </term>
6531     <listitem><para>
6532         The sconscript file (that is, &SConstruct; or &SConscript;
6533         file) that will be invoked by &MSVC; project files
6534         (through the &cv-link-MSVSSCONSCOM; variable). The default
6535         is the same sconscript file that contains the call to
6536         &b-link-MSVSProject; to build the project file.
6537       </para>
6538     </listitem>
6539   </varlistentry>
6540   <varlistentry id="cv-MSVSSCONSFLAGS">
6541     <term>
6542       <envar>MSVSSCONSFLAGS</envar>
6543     </term>
6544     <listitem><para>
6545         The &SCons; flags used in generated &MSVC; project files.
6546       </para>
6547     </listitem>
6548   </varlistentry>
6549   <varlistentry id="cv-MSVSSOLUTIONCOM">
6550     <term>
6551       <envar>MSVSSOLUTIONCOM</envar>
6552     </term>
6553     <listitem><para>The action used to generate Microsoft Visual Studio solution files.</para>
6554     </listitem>
6555   </varlistentry>
6556   <varlistentry id="cv-MSVSSOLUTIONSUFFIX">
6557     <term>
6558       <envar>MSVSSOLUTIONSUFFIX</envar>
6559     </term>
6560     <listitem><para>
6561         The suffix used for Microsoft Visual Studio solution (DSW)
6562         files. The default value is <filename>.sln</filename>
6563         when using Visual Studio version 7.x (.NET 2002) and later,
6564         and <filename>.dsw</filename> when using Visual Studio 6.0.
6565       </para>
6566     </listitem>
6567   </varlistentry>
6568   <varlistentry id="cv-MT">
6569     <term>
6570       <envar>MT</envar>
6571     </term>
6572     <listitem><para>
6573 The program used on Windows systems to embed manifests into DLLs and EXEs.
6574 See also &cv-link-WINDOWS_EMBED_MANIFEST;.
6575 </para>
6576 </listitem>
6577   </varlistentry>
6578   <varlistentry id="cv-MTEXECOM">
6579     <term>
6580       <envar>MTEXECOM</envar>
6581     </term>
6582     <listitem><para>
6583 The Windows command line used to embed manifests into executables.
6584 See also &cv-link-MTSHLIBCOM;.
6585 </para>
6586 </listitem>
6587   </varlistentry>
6588   <varlistentry id="cv-MTFLAGS">
6589     <term>
6590       <envar>MTFLAGS</envar>
6591     </term>
6592     <listitem><para>
6593 Flags passed to the &cv-link-MT; manifest embedding program (Windows only).
6594 </para>
6595 </listitem>
6596   </varlistentry>
6597   <varlistentry id="cv-MTSHLIBCOM">
6598     <term>
6599       <envar>MTSHLIBCOM</envar>
6600     </term>
6601     <listitem><para>
6602 The Windows command line used to embed manifests into shared libraries (DLLs).
6603 See also &cv-link-MTEXECOM;.
6604 </para>
6605 </listitem>
6606   </varlistentry>
6607   <varlistentry id="cv-MWCW_VERSION">
6608     <term>
6609       <envar>MWCW_VERSION</envar>
6610     </term>
6611     <listitem><para>
6612 The version number of the MetroWerks CodeWarrior C compiler
6613 to be used.
6614 </para>
6615 </listitem>
6616   </varlistentry>
6617   <varlistentry id="cv-MWCW_VERSIONS">
6618     <term>
6619       <envar>MWCW_VERSIONS</envar>
6620     </term>
6621     <listitem><para>
6622 A list of installed versions of the MetroWerks CodeWarrior C compiler
6623 on this system.
6624 </para>
6625 </listitem>
6626   </varlistentry>
6627   <varlistentry id="cv-NAME">
6628     <term>
6629       <envar>NAME</envar>
6630     </term>
6631     <listitem><para>
6632 Specfies the name of the project to package.
6633 </para>
6634 <para>See the &b-link-Package; builder.</para>
6635 </listitem>
6636   </varlistentry>
6637   <varlistentry id="cv-NINJA_ALIAS_NAME">
6638     <term>
6639       <envar>NINJA_ALIAS_NAME</envar>
6640     </term>
6641     <listitem><para>
6642                 The name of the alias target which will cause &SCons; to create the &ninja; build file,
6643                 and then (optionally) run &ninja;.
6644                 The default value is <literal>generate-ninja</literal>.
6645             </para>
6646         </listitem>
6647   </varlistentry>
6648   <varlistentry id="cv-NINJA_CMD_ARGS">
6649     <term>
6650       <envar>NINJA_CMD_ARGS</envar>
6651     </term>
6652     <listitem><para>
6653                 A string which will pass arguments through SCons to the ninja command when scons executes ninja.
6654                 Has no effect if &cv-NINJA_DISABLE_AUTO_RUN; is set.
6655             </para>
6656             <para>
6657                 This value can also be passed on the command line:
6658             </para>
6659             <example_commands>
6660 scons NINJA_CMD_ARGS=-v
6661 or
6662 scons NINJA_CMD_ARGS="-v -j 3"
6663             </example_commands>
6664         </listitem>
6665   </varlistentry>
6666   <varlistentry id="cv-NINJA_COMPDB_EXPAND">
6667     <term>
6668       <envar>NINJA_COMPDB_EXPAND</envar>
6669     </term>
6670     <listitem><para>
6671                 Boolean value to instruct &ninja; to expand the command line arguments normally put into
6672                 response files.
6673                 If true, prevents unexpanded lines in the compilation database like
6674                 <quote><literal>gcc @rsp_file</literal></quote> and instead yields expanded lines like
6675                 <quote><literal>gcc -c -o myfile.o myfile.c -Ia -DXYZ</literal></quote>.
6676             </para>
6677             <para>
6678                 Ninja's compdb tool added the <option>-x</option> flag in Ninja V1.9.0
6679             </para>
6680         </listitem>
6681   </varlistentry>
6682   <varlistentry id="cv-NINJA_DEPFILE_PARSE_FORMAT">
6683     <term>
6684       <envar>NINJA_DEPFILE_PARSE_FORMAT</envar>
6685     </term>
6686     <listitem><para>
6687                 Determines the type of format ninja should expect when parsing header
6688                 include depfiles. Can be <option>msvc</option>, <option>gcc</option>, or <option>clang</option>.
6689                 The <option>msvc</option> option corresponds to <option>/showIncludes</option> format, and
6690                 <option>gcc</option> or <option>clang</option> correspond to <option>-MMD -MF</option>.
6691             </para>
6692         </listitem>
6693   </varlistentry>
6694   <varlistentry id="cv-NINJA_DIR">
6695     <term>
6696       <envar>NINJA_DIR</envar>
6697     </term>
6698     <listitem><para>
6699                 The <parameter>builddir</parameter> value.
6700                 Propagates directly into the generated &ninja; build file.
6701                 From Ninja's docs:
6702                 <quote>
6703                     A directory for some Ninja output files. ... (You can also store other build output in this
6704                     directory.)
6705                 </quote>
6706             The default value is <filename>.ninja</filename>.
6707             </para>
6708         </listitem>
6709   </varlistentry>
6710   <varlistentry id="cv-NINJA_DISABLE_AUTO_RUN">
6711     <term>
6712       <envar>NINJA_DISABLE_AUTO_RUN</envar>
6713     </term>
6714     <listitem><para>
6715                 Boolean. Default: <constant>False</constant>.
6716                 If true, &SCons; will not run &ninja; automatically after creating the &ninja; build file.
6717             </para>
6718
6719             <para>
6720                 If not explicitly set, this will be set to <constant>True</constant>
6721                 if <option>--disable_execute_ninja</option> or
6722                 <code>SetOption('disable_execute_ninja', True)</code> is seen.
6723             </para>
6724         </listitem>
6725   </varlistentry>
6726   <varlistentry id="cv-NINJA_ENV_VAR_CACHE">
6727     <term>
6728       <envar>NINJA_ENV_VAR_CACHE</envar>
6729     </term>
6730     <listitem><para>
6731                 A string that sets the environment for any environment variables that
6732                 differ between the OS environment and the &SCons; execution environment.
6733             </para>
6734
6735             <para>
6736                 It will be compatible with the default shell of the operating system.
6737             </para>
6738
6739             <para>
6740                 If not explicitly set, &SCons; will generate this dynamically from the
6741                 execution environment stored in the current &consenv;
6742                 (e.g. <literal>env['ENV']</literal>)
6743                 where those values differ from the existing shell..
6744             </para>
6745         </listitem>
6746   </varlistentry>
6747   <varlistentry id="cv-NINJA_FILE_NAME">
6748     <term>
6749       <envar>NINJA_FILE_NAME</envar>
6750     </term>
6751     <listitem><para>
6752                 The filename for the generated Ninja build file.
6753                 The default is <filename>ninja.build</filename>.
6754             </para>
6755         </listitem>
6756   </varlistentry>
6757   <varlistentry id="cv-NINJA_FORCE_SCONS_BUILD">
6758     <term>
6759       <envar>NINJA_FORCE_SCONS_BUILD</envar>
6760     </term>
6761     <listitem><para>
6762                 If true, causes the build nodes to callback to scons instead of using
6763                 &ninja; to build them. This is intended to be passed to the environment on the builder invocation.
6764                 It is useful if you have a build node which does something which is not easily translated into &ninja;.
6765             </para>
6766         </listitem>
6767   </varlistentry>
6768   <varlistentry id="cv-NINJA_GENERATED_SOURCE_ALIAS_NAME">
6769     <term>
6770       <envar>NINJA_GENERATED_SOURCE_ALIAS_NAME</envar>
6771     </term>
6772     <listitem><para>
6773                 A string matching the name of a user defined alias which represents a list of all generated sources.
6774                 This will prevent the auto-detection of generated sources from &cv-NINJA_GENERATED_SOURCE_SUFFIXES;.
6775                 Then all other source files will be made to depend on this in the &ninja; build file, forcing the
6776                 generated sources to be built first.
6777             </para>
6778         </listitem>
6779   </varlistentry>
6780   <varlistentry id="cv-NINJA_GENERATED_SOURCE_SUFFIXES">
6781     <term>
6782       <envar>NINJA_GENERATED_SOURCE_SUFFIXES</envar>
6783     </term>
6784     <listitem><para>
6785                 The list of source file suffixes which are generated by &SCons; build steps.
6786                 All source files which match these suffixes will be added to the _generated_sources alias in the output
6787                 &ninja; build file.
6788                 Then all other source files will be made to depend on this in the &ninja; build file, forcing the
6789                 generated sources to be built first.
6790             </para>
6791         </listitem>
6792   </varlistentry>
6793   <varlistentry id="cv-NINJA_MSVC_DEPS_PREFIX">
6794     <term>
6795       <envar>NINJA_MSVC_DEPS_PREFIX</envar>
6796     </term>
6797     <listitem><para>
6798                 The <parameter>msvc_deps_prefix</parameter> string.
6799                 Propagates directly into the generated &ninja; build file.
6800                 From Ninja's docs:
6801                 <quote>defines the string which should be stripped from msvc's <option>/showIncludes</option> output</quote>
6802             </para>
6803         </listitem>
6804   </varlistentry>
6805   <varlistentry id="cv-NINJA_POOL">
6806     <term>
6807       <envar>NINJA_POOL</envar>
6808     </term>
6809     <listitem><para>
6810                 Set the <parameter>ninja_pool</parameter> for this or all targets in scope for this env var.
6811             </para>
6812         </listitem>
6813   </varlistentry>
6814   <varlistentry id="cv-NINJA_REGENERATE_DEPS">
6815     <term>
6816       <envar>NINJA_REGENERATE_DEPS</envar>
6817     </term>
6818     <listitem><para>
6819                 A generator function used to create a &ninja; depfile which
6820                 includes all the files which would require
6821                 &SCons; to be invoked if they change.
6822                 Or a list of said files.
6823             </para>
6824         </listitem>
6825   </varlistentry>
6826   <varlistentry id="cv-_NINJA_REGENERATE_DEPS_FUNC">
6827     <term>
6828       <envar>_NINJA_REGENERATE_DEPS_FUNC</envar>
6829     </term>
6830     <listitem><para>
6831                 Internal value used to specify the function to call with argument env to generate the list of files
6832                 which if changed would require the &ninja; build file to be regenerated.
6833             </para>
6834         </listitem>
6835   </varlistentry>
6836   <varlistentry id="cv-NINJA_SCONS_DAEMON_KEEP_ALIVE">
6837     <term>
6838       <envar>NINJA_SCONS_DAEMON_KEEP_ALIVE</envar>
6839     </term>
6840     <listitem><para>
6841                 The number of seconds for the SCons deamon launched by ninja to stay alive.
6842                 (Default: 180000)
6843             </para>
6844         </listitem>
6845   </varlistentry>
6846   <varlistentry id="cv-NINJA_SCONS_DAEMON_PORT">
6847     <term>
6848       <envar>NINJA_SCONS_DAEMON_PORT</envar>
6849     </term>
6850     <listitem><para>
6851                 The TCP/IP port for the SCons daemon to listen on.
6852                 <emphasis>NOTE: You cannot use a port already being listened to on your build machine.</emphasis>
6853                 (Default: random number between 10000,60000)
6854             </para>
6855         </listitem>
6856   </varlistentry>
6857   <varlistentry id="cv-NINJA_SYNTAX">
6858     <term>
6859       <envar>NINJA_SYNTAX</envar>
6860     </term>
6861     <listitem><para>
6862                 The path to a custom <filename>ninja_syntax.py</filename> file which is used in generation.
6863                 The tool currently assumes you have &ninja; installed as a &Python; module and grabs the syntax file from that
6864                 installation if &cv-NINJA_SYNTAX; is not explicitly set.
6865             </para>
6866         </listitem>
6867   </varlistentry>
6868   <varlistentry id="cv-no_import_lib">
6869     <term>
6870       <envar>no_import_lib</envar>
6871     </term>
6872     <listitem><para>
6873 When set to non-zero,
6874 suppresses creation of a corresponding Windows static import lib by the
6875 &b-link-SharedLibrary;
6876 builder when used with
6877 MinGW, Microsoft Visual Studio or Metrowerks.
6878 This also suppresses creation
6879 of an export (<filename>.exp</filename>) file
6880 when using Microsoft Visual Studio.
6881 </para>
6882 </listitem>
6883   </varlistentry>
6884   <varlistentry id="cv-OBJPREFIX">
6885     <term>
6886       <envar>OBJPREFIX</envar>
6887     </term>
6888     <listitem><para>
6889 The prefix used for (static) object file names.
6890 </para>
6891 </listitem>
6892   </varlistentry>
6893   <varlistentry id="cv-OBJSUFFIX">
6894     <term>
6895       <envar>OBJSUFFIX</envar>
6896     </term>
6897     <listitem><para>
6898 The suffix used for (static) object file names.
6899 </para>
6900 </listitem>
6901   </varlistentry>
6902   <varlistentry id="cv-PACKAGEROOT">
6903     <term>
6904       <envar>PACKAGEROOT</envar>
6905     </term>
6906     <listitem><para>
6907 Specifies the directory where all files in resulting archive will be
6908 placed if applicable.  The default value is <quote>&cv-NAME;-&cv-VERSION;</quote>.
6909 </para>
6910 <para>See the &b-link-Package; builder.</para>
6911 </listitem>
6912   </varlistentry>
6913   <varlistentry id="cv-PACKAGETYPE">
6914     <term>
6915       <envar>PACKAGETYPE</envar>
6916     </term>
6917     <listitem><para>
6918 Selects the package type to build when using the &b-link-Package;
6919 builder. May be a string or list of strings. See the docuentation
6920 for the builder for the currently supported types.
6921 </para>
6922
6923 <para>
6924 &cv-PACKAGETYPE; may be overridden with the <option>--package-type</option>
6925 command line option.
6926 </para>
6927 <para>See the &b-link-Package; builder.</para>
6928 </listitem>
6929   </varlistentry>
6930   <varlistentry id="cv-PACKAGEVERSION">
6931     <term>
6932       <envar>PACKAGEVERSION</envar>
6933     </term>
6934     <listitem><para>
6935 The version of the package (not the underlying project).
6936 This is currently only used by the rpm packager
6937 and should reflect changes in the packaging,
6938 not the underlying project code itself.
6939 </para>
6940 <para>See the &b-link-Package; builder.</para>
6941 </listitem>
6942   </varlistentry>
6943   <varlistentry id="cv-PCH">
6944     <term>
6945       <envar>PCH</envar>
6946     </term>
6947     <listitem><para>
6948 A node for the &MSVC; precompiled header that will be
6949 used when compiling object files.
6950 This variable is ignored by tools other than &MSVC;.
6951 When this variable is
6952 defined, &SCons; will add options to the compiler command line to
6953 cause it to use the precompiled header, and will also set up the
6954 dependencies for the PCH file.
6955 Examples:
6956 </para>
6957
6958 <example_commands>
6959 env['PCH'] = File('StdAfx.pch')
6960 env['PCH'] = env.PCH('pch.cc')[0]
6961 </example_commands>
6962 </listitem>
6963   </varlistentry>
6964   <varlistentry id="cv-PCHCOM">
6965     <term>
6966       <envar>PCHCOM</envar>
6967     </term>
6968     <listitem><para>
6969 The command line used by the
6970 &b-link-PCH;
6971 builder to generated a precompiled header.
6972 </para>
6973 </listitem>
6974   </varlistentry>
6975   <varlistentry id="cv-PCHCOMSTR">
6976     <term>
6977       <envar>PCHCOMSTR</envar>
6978     </term>
6979     <listitem><para>
6980 The string displayed when generating a precompiled header.
6981 If not set, then &cv-link-PCHCOM; (the command line) is displayed.
6982 </para>
6983 </listitem>
6984   </varlistentry>
6985   <varlistentry id="cv-PCHPDBFLAGS">
6986     <term>
6987       <envar>PCHPDBFLAGS</envar>
6988     </term>
6989     <listitem><para>
6990 A &consvar; that, when expanded,
6991 adds the <option>/yD</option> flag to the command line
6992 only if the &cv-link-PDB; &consvar; is set.
6993 </para>
6994 </listitem>
6995   </varlistentry>
6996   <varlistentry id="cv-PCHSTOP">
6997     <term>
6998       <envar>PCHSTOP</envar>
6999     </term>
7000     <listitem><para>
7001 This variable specifies how much of a source file is precompiled. This
7002 variable is ignored by tools other than &MSVC;, or when
7003 the PCH variable is not being used. When this variable is define it
7004 must be a string that is the name of the header that
7005 is included at the end of the precompiled portion of the source files, or
7006 the empty string if the "#pragma hrdstop" construct is being used:
7007 </para>
7008
7009 <example_commands>
7010 env['PCHSTOP'] = 'StdAfx.h'
7011 </example_commands>
7012 </listitem>
7013   </varlistentry>
7014   <varlistentry id="cv-PDB">
7015     <term>
7016       <envar>PDB</envar>
7017     </term>
7018     <listitem><para>
7019 The &MSVC; PDB file that will store debugging information for
7020 object files, shared libraries, and programs. This variable is ignored by
7021 tools other than &MSVC;.
7022 When this variable is
7023 defined SCons will add options to the compiler and linker command line to
7024 cause them to generate external debugging information, and will also set up the
7025 dependencies for the PDB file.
7026 Example:
7027 </para>
7028
7029 <example_commands>
7030 env['PDB'] = 'hello.pdb'
7031 </example_commands>
7032
7033 <para>
7034 The &MSVC; compiler switch that SCons uses by default
7035 to generate PDB information is <option>/Z7</option>.
7036 This works correctly with parallel (<option>-j</option>) builds
7037 because it embeds the debug information in the intermediate object files,
7038 as opposed to sharing a single PDB file between multiple object files.
7039 This is also the only way to get debug information
7040 embedded into a static library.
7041 Using the <option>/Zi</option> instead may yield improved
7042 link-time performance,
7043 although parallel builds will no longer work.
7044 You can generate PDB files with the <option>/Zi</option>
7045 switch by overriding the default &cv-link-CCPDBFLAGS; variable;
7046 see the entry for that variable for specific examples.
7047 </para>
7048 </listitem>
7049   </varlistentry>
7050   <varlistentry id="cv-PDFLATEX">
7051     <term>
7052       <envar>PDFLATEX</envar>
7053     </term>
7054     <listitem><para>
7055 The &pdflatex; utility.
7056 </para>
7057 </listitem>
7058   </varlistentry>
7059   <varlistentry id="cv-PDFLATEXCOM">
7060     <term>
7061       <envar>PDFLATEXCOM</envar>
7062     </term>
7063     <listitem><para>
7064 The command line used to call the &pdflatex; utility.
7065 </para>
7066 </listitem>
7067   </varlistentry>
7068   <varlistentry id="cv-PDFLATEXCOMSTR">
7069     <term>
7070       <envar>PDFLATEXCOMSTR</envar>
7071     </term>
7072     <listitem><para>
7073 The string displayed when calling the &pdflatex; utility.
7074 If this is not set, then &cv-link-PDFLATEXCOM; (the command line) is displayed.
7075 </para>
7076
7077 <example_commands>
7078 env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")
7079 </example_commands>
7080 </listitem>
7081   </varlistentry>
7082   <varlistentry id="cv-PDFLATEXFLAGS">
7083     <term>
7084       <envar>PDFLATEXFLAGS</envar>
7085     </term>
7086     <listitem><para>
7087 General options passed to the &pdflatex; utility.
7088 </para>
7089 </listitem>
7090   </varlistentry>
7091   <varlistentry id="cv-PDFPREFIX">
7092     <term>
7093       <envar>PDFPREFIX</envar>
7094     </term>
7095     <listitem><para>
7096 The prefix used for PDF file names.
7097 </para>
7098 </listitem>
7099   </varlistentry>
7100   <varlistentry id="cv-PDFSUFFIX">
7101     <term>
7102       <envar>PDFSUFFIX</envar>
7103     </term>
7104     <listitem><para>
7105 The suffix used for PDF file names.
7106 </para>
7107 </listitem>
7108   </varlistentry>
7109   <varlistentry id="cv-PDFTEX">
7110     <term>
7111       <envar>PDFTEX</envar>
7112     </term>
7113     <listitem><para>
7114 The &pdftex; utility.
7115 </para>
7116 </listitem>
7117   </varlistentry>
7118   <varlistentry id="cv-PDFTEXCOM">
7119     <term>
7120       <envar>PDFTEXCOM</envar>
7121     </term>
7122     <listitem><para>
7123 The command line used to call the &pdftex; utility.
7124 </para>
7125 </listitem>
7126   </varlistentry>
7127   <varlistentry id="cv-PDFTEXCOMSTR">
7128     <term>
7129       <envar>PDFTEXCOMSTR</envar>
7130     </term>
7131     <listitem><para>
7132 The string displayed when calling the &pdftex; utility.
7133 If this is not set, then &cv-link-PDFTEXCOM; (the command line) is displayed.
7134 </para>
7135
7136 <example_commands>
7137 env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
7138 </example_commands>
7139 </listitem>
7140   </varlistentry>
7141   <varlistentry id="cv-PDFTEXFLAGS">
7142     <term>
7143       <envar>PDFTEXFLAGS</envar>
7144     </term>
7145     <listitem><para>
7146 General options passed to the &pdftex; utility.
7147 </para>
7148 </listitem>
7149   </varlistentry>
7150   <varlistentry id="cv-PKGCHK">
7151     <term>
7152       <envar>PKGCHK</envar>
7153     </term>
7154     <listitem><para>
7155 On Solaris systems,
7156 the package-checking program that will
7157 be used (along with &cv-PKGINFO;)
7158 to look for installed versions of
7159 the Sun PRO C++ compiler.
7160 The default is
7161 <filename>/usr/sbin/pgkchk</filename>.
7162 </para>
7163 </listitem>
7164   </varlistentry>
7165   <varlistentry id="cv-PKGINFO">
7166     <term>
7167       <envar>PKGINFO</envar>
7168     </term>
7169     <listitem><para>
7170 On Solaris systems,
7171 the package information program that will
7172 be used (along with &cv-PKGCHK;)
7173 to look for installed versions of
7174 the Sun PRO C++ compiler.
7175 The default is
7176 <filename>pkginfo</filename>.
7177 </para>
7178 </listitem>
7179   </varlistentry>
7180   <varlistentry id="cv-PLATFORM">
7181     <term>
7182       <envar>PLATFORM</envar>
7183     </term>
7184     <listitem><para>
7185       The name of the platform used to create this &consenv;.
7186       &SCons; sets this when initializing the platform,
7187       which by default is auto-detected
7188       (see the <parameter>platform</parameter>
7189       argument to &f-link-Environment;).
7190     </para>
7191
7192     <example_commands>
7193 env = Environment(tools=[])
7194 if env['PLATFORM'] == 'cygwin':
7195     Tool('mingw')(env)
7196 else:
7197     Tool('msvc')(env)
7198     </example_commands>
7199   </listitem>
7200   </varlistentry>
7201   <varlistentry id="cv-POAUTOINIT">
7202     <term>
7203       <envar>POAUTOINIT</envar>
7204     </term>
7205     <listitem><para>
7206 The &cv-POAUTOINIT; variable, if set to <literal>True</literal> (on non-zero
7207 numeric value), let the &t-link-msginit; tool to automatically initialize
7208 <emphasis>missing</emphasis> <literal>PO</literal> files with
7209 <command>msginit(1)</command>.  This applies to both,
7210 &b-link-POInit; and &b-link-POUpdate; builders (and others that use any of
7211 them).
7212 </para>
7213 </listitem>
7214   </varlistentry>
7215   <varlistentry id="cv-POCREATE_ALIAS">
7216     <term>
7217       <envar>POCREATE_ALIAS</envar>
7218     </term>
7219     <listitem><para>
7220 Common alias for all <literal>PO</literal> files created with &b-POInit;
7221 builder (default: <literal>'po-create'</literal>).
7222 See &t-link-msginit; tool and &b-link-POInit; builder.
7223 </para>
7224 </listitem>
7225   </varlistentry>
7226   <varlistentry id="cv-POSUFFIX">
7227     <term>
7228       <envar>POSUFFIX</envar>
7229     </term>
7230     <listitem><para>
7231 Suffix used for <literal>PO</literal> files (default: <literal>'.po'</literal>)
7232 See &t-link-msginit; tool and &b-link-POInit; builder.
7233 </para>
7234 </listitem>
7235   </varlistentry>
7236   <varlistentry id="cv-POTDOMAIN">
7237     <term>
7238       <envar>POTDOMAIN</envar>
7239     </term>
7240     <listitem><para>
7241 The &cv-POTDOMAIN; defines default domain, used to generate
7242 <literal>POT</literal> filename as <filename>&cv-POTDOMAIN;.pot</filename> when
7243 no <literal>POT</literal> file name is provided by the user. This applies to
7244 &b-link-POTUpdate;, &b-link-POInit; and &b-link-POUpdate; builders (and
7245 builders, that use them, e.g. &b-Translate;). Normally (if &cv-POTDOMAIN; is
7246 not defined), the builders use <filename>messages.pot</filename> as default
7247 <literal>POT</literal> file name.
7248 </para>
7249 </listitem>
7250   </varlistentry>
7251   <varlistentry id="cv-POTSUFFIX">
7252     <term>
7253       <envar>POTSUFFIX</envar>
7254     </term>
7255     <listitem><para>
7256 Suffix used for PO Template files (default: <literal>'.pot'</literal>).
7257 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
7258 </para>
7259 </listitem>
7260   </varlistentry>
7261   <varlistentry id="cv-POTUPDATE_ALIAS">
7262     <term>
7263       <envar>POTUPDATE_ALIAS</envar>
7264     </term>
7265     <listitem><para>
7266 Name of the common phony target for all PO Templates created with
7267 &b-link-POUpdate; (default: <literal>'pot-update'</literal>).
7268 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
7269 </para>
7270 </listitem>
7271   </varlistentry>
7272   <varlistentry id="cv-POUPDATE_ALIAS">
7273     <term>
7274       <envar>POUPDATE_ALIAS</envar>
7275     </term>
7276     <listitem><para>
7277 Common alias for all <literal>PO</literal> files being defined with
7278 &b-link-POUpdate; builder (default: <literal>'po-update'</literal>).
7279 See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
7280 </para>
7281 </listitem>
7282   </varlistentry>
7283   <varlistentry id="cv-PRINT_CMD_LINE_FUNC">
7284     <term>
7285       <envar>PRINT_CMD_LINE_FUNC</envar>
7286     </term>
7287     <listitem><para>
7288 A Python function used to print the command lines as they are executed
7289 (assuming command printing is not disabled by the
7290 <option>-q</option>
7291 or
7292 <option>-s</option>
7293 options or their equivalents).
7294 The function must accept four arguments:
7295 <varname>s</varname>,
7296 <varname>target</varname>,
7297 <varname>source</varname> and
7298 <varname>env</varname>.
7299 <varname>s</varname>
7300 is a string showing the command being executed,
7301 <varname>target</varname>,
7302 is the target being built (file node, list, or string name(s)),
7303 <varname>source</varname>,
7304 is the source(s) used (file node, list, or string name(s)),
7305 and <varname>env</varname>
7306 is the environment being used.
7307 </para>
7308
7309 <para>
7310 The function must do the printing itself.
7311 The default implementation,
7312 used if this variable is not set or is <constant>None</constant>,
7313 is to just print the string, as in:
7314 </para>
7315 <example_commands>
7316 def print_cmd_line(s, target, source, env):
7317     sys.stdout.write(s + "\n")
7318 </example_commands>
7319
7320 <para>
7321 Here is an example of a more interesting function:
7322 </para>
7323
7324 <example_commands>
7325 def print_cmd_line(s, target, source, env):
7326     sys.stdout.write(
7327         "Building %s -&gt; %s...\n"
7328         % (
7329             ' and '.join([str(x) for x in source]),
7330             ' and '.join([str(x) for x in target]),
7331         )
7332     )
7333
7334 env = Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
7335 env.Program('foo', ['foo.c', 'bar.c'])
7336 </example_commands>
7337
7338 <para>
7339 This prints:
7340 </para>
7341
7342 <screen>
7343 ...
7344 scons: Building targets ...
7345 Building bar.c -&gt; bar.o...
7346 Building foo.c -&gt; foo.o...
7347 Building foo.o and bar.o -&gt; foo...
7348 scons: done building targets.
7349 </screen>
7350
7351 <para>
7352 Another example could be a function that logs the actual commands to a file.
7353 </para>
7354 </listitem>
7355   </varlistentry>
7356   <varlistentry id="cv-PROGEMITTER">
7357     <term>
7358       <envar>PROGEMITTER</envar>
7359     </term>
7360     <listitem><para>
7361 Contains the emitter specification for the
7362 &b-link-Program; builder.
7363 The manpage section "Builder Objects" contains
7364 general information on specifying emitters.
7365 </para>
7366 </listitem>
7367   </varlistentry>
7368   <varlistentry id="cv-PROGPREFIX">
7369     <term>
7370       <envar>PROGPREFIX</envar>
7371     </term>
7372     <listitem><para>
7373 The prefix used for executable file names.
7374 </para>
7375 </listitem>
7376   </varlistentry>
7377   <varlistentry id="cv-PROGSUFFIX">
7378     <term>
7379       <envar>PROGSUFFIX</envar>
7380     </term>
7381     <listitem><para>
7382 The suffix used for executable file names.
7383 </para>
7384 </listitem>
7385   </varlistentry>
7386   <varlistentry id="cv-PSCOM">
7387     <term>
7388       <envar>PSCOM</envar>
7389     </term>
7390     <listitem><para>
7391 The command line used to convert TeX DVI files into a PostScript file.
7392 </para>
7393 </listitem>
7394   </varlistentry>
7395   <varlistentry id="cv-PSCOMSTR">
7396     <term>
7397       <envar>PSCOMSTR</envar>
7398     </term>
7399     <listitem><para>
7400 The string displayed when a TeX DVI file
7401 is converted into a PostScript file.
7402 If this is not set, then &cv-link-PSCOM; (the command line) is displayed.
7403 </para>
7404 </listitem>
7405   </varlistentry>
7406   <varlistentry id="cv-PSPREFIX">
7407     <term>
7408       <envar>PSPREFIX</envar>
7409     </term>
7410     <listitem><para>
7411 The prefix used for PostScript file names.
7412 </para>
7413 </listitem>
7414   </varlistentry>
7415   <varlistentry id="cv-PSSUFFIX">
7416     <term>
7417       <envar>PSSUFFIX</envar>
7418     </term>
7419     <listitem><para>
7420 The prefix used for PostScript file names.
7421 </para>
7422 </listitem>
7423   </varlistentry>
7424   <varlistentry id="cv-QT3_AUTOSCAN">
7425     <term>
7426       <envar>QT3_AUTOSCAN</envar>
7427     </term>
7428     <listitem><para>
7429 Turn off scanning for mocable files. Use the &b-link-Moc; Builder to explicitly
7430 specify files to run <command>moc</command> on.
7431 </para>
7432 <para>
7433 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_AUTOSCAN.
7434 </para>
7435 </listitem>
7436   </varlistentry>
7437   <varlistentry id="cv-QT3_BINPATH">
7438     <term>
7439       <envar>QT3_BINPATH</envar>
7440     </term>
7441     <listitem><para>
7442 The path where the Qt binaries are installed.
7443 The default value is '&cv-link-QT3DIR;<filename>/bin</filename>'.
7444 </para>
7445 <para>
7446 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_BINPATH.
7447 </para>
7448 </listitem>
7449   </varlistentry>
7450   <varlistentry id="cv-QT3_CPPPATH">
7451     <term>
7452       <envar>QT3_CPPPATH</envar>
7453     </term>
7454     <listitem><para>
7455 The path where the Qt header files are installed.
7456 The default value is '&cv-link-QT3DIR;/include'.
7457 Note: If you set this variable to <constant>None</constant>,
7458 the tool won't change the &cv-link-CPPPATH;
7459 construction variable.
7460 </para>
7461 <para>
7462 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_CPPPATH.
7463 </para>
7464 </listitem>
7465   </varlistentry>
7466   <varlistentry id="cv-QT3_DEBUG">
7467     <term>
7468       <envar>QT3_DEBUG</envar>
7469     </term>
7470     <listitem><para>
7471 Prints lots of debugging information while scanning for moc files.
7472 </para>
7473 <para>
7474 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_DEBUG.
7475 </para>
7476 </listitem>
7477   </varlistentry>
7478   <varlistentry id="cv-QT3_LIB">
7479     <term>
7480       <envar>QT3_LIB</envar>
7481     </term>
7482     <listitem><para>
7483 Default value is <literal>'qt'</literal>.
7484 You may want to set this to <literal>'qt-mt'</literal>.
7485 Note: If you set this variable to <constant>None</constant>,
7486 the tool won't change the &cv-link-LIBS; variable.
7487 </para>
7488 <para>
7489 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_LIB.
7490 </para>
7491 </listitem>
7492   </varlistentry>
7493   <varlistentry id="cv-QT3_LIBPATH">
7494     <term>
7495       <envar>QT3_LIBPATH</envar>
7496     </term>
7497     <listitem><para>
7498 The path where the Qt libraries are installed.
7499 The default value is '&cv-link-QT3DIR;<filename>/lib</filename>'.
7500 Note: If you set this variable to <constant>None</constant>,
7501 the tool won't change the &cv-link-LIBPATH;
7502 construction variable.
7503 </para>
7504 <para>
7505 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_LIBPATH.
7506 </para>
7507 </listitem>
7508   </varlistentry>
7509   <varlistentry id="cv-QT3_MOC">
7510     <term>
7511       <envar>QT3_MOC</envar>
7512     </term>
7513     <listitem><para>
7514 Default value is '&cv-link-QT3_BINPATH;<filename>/moc</filename>'.
7515 </para>
7516 </listitem>
7517   </varlistentry>
7518   <varlistentry id="cv-QT3_MOCCXXPREFIX">
7519     <term>
7520       <envar>QT3_MOCCXXPREFIX</envar>
7521     </term>
7522     <listitem><para>
7523 Default value is <literal>''</literal>.
7524 Prefix for <command>moc</command> output files when source is a C++ file.
7525 </para>
7526 </listitem>
7527   </varlistentry>
7528   <varlistentry id="cv-QT3_MOCCXXSUFFIX">
7529     <term>
7530       <envar>QT3_MOCCXXSUFFIX</envar>
7531     </term>
7532     <listitem><para>
7533 Default value is <literal>'.moc'</literal>.
7534 Suffix for <command>moc</command> output files when source is a C++ file.
7535 </para>
7536 <para>
7537 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCCXXSUFFIX.
7538 </para>
7539 </listitem>
7540   </varlistentry>
7541   <varlistentry id="cv-QT3_MOCFROMCXXCOM">
7542     <term>
7543       <envar>QT3_MOCFROMCXXCOM</envar>
7544     </term>
7545     <listitem><para>
7546 Command to generate a moc file from a C++ file.
7547 </para>
7548 <para>
7549 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMCXXCOM.
7550 </para>
7551 </listitem>
7552   </varlistentry>
7553   <varlistentry id="cv-QT3_MOCFROMCXXCOMSTR">
7554     <term>
7555       <envar>QT3_MOCFROMCXXCOMSTR</envar>
7556     </term>
7557     <listitem><para>
7558 The string displayed when generating a moc file from a C++ file.
7559 If this is not set, then &cv-link-QT3_MOCFROMCXXCOM; (the command line) is displayed.
7560 </para>
7561 <para>
7562 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMCXXCOMSTR.
7563 </para>
7564 </listitem>
7565   </varlistentry>
7566   <varlistentry id="cv-QT3_MOCFROMCXXFLAGS">
7567     <term>
7568       <envar>QT3_MOCFROMCXXFLAGS</envar>
7569     </term>
7570     <listitem><para>
7571 Default value is <literal>'-i'</literal>.
7572 These flags are passed to <command>moc</command> when moccing a C++ file.
7573 </para>
7574 <para>
7575 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMCXXFLAGS.
7576 </para>
7577 </listitem>
7578   </varlistentry>
7579   <varlistentry id="cv-QT3_MOCFROMHCOM">
7580     <term>
7581       <envar>QT3_MOCFROMHCOM</envar>
7582     </term>
7583     <listitem><para>
7584 Command to generate a moc file from a header.
7585 </para>
7586 <para>
7587 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMSHCOM.
7588 </para>
7589 </listitem>
7590   </varlistentry>
7591   <varlistentry id="cv-QT3_MOCFROMHCOMSTR">
7592     <term>
7593       <envar>QT3_MOCFROMHCOMSTR</envar>
7594     </term>
7595     <listitem><para>
7596 The string displayed when generating a moc file from a C++ file.
7597 If this is not set, then &cv-link-QT3_MOCFROMHCOM; (the command line) is displayed.
7598 </para>
7599 <para>
7600 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMSHCOMSTR.
7601 </para>
7602 </listitem>
7603   </varlistentry>
7604   <varlistentry id="cv-QT3_MOCFROMHFLAGS">
7605     <term>
7606       <envar>QT3_MOCFROMHFLAGS</envar>
7607     </term>
7608     <listitem><para>
7609 Default value is <literal>''</literal>. These flags are passed to <command>moc</command>
7610 when moccing a header file.
7611 </para>
7612 <para>
7613 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMSHFLAGS.
7614 </para>
7615 </listitem>
7616   </varlistentry>
7617   <varlistentry id="cv-QT3_MOCHPREFIX">
7618     <term>
7619       <envar>QT3_MOCHPREFIX</envar>
7620     </term>
7621     <listitem><para>
7622 Default value is <literal>'moc_'</literal>.
7623 Prefix for <command>moc</command> output files when source is a header.
7624 </para>
7625 <para>
7626 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCHPREFIX.
7627 </para>
7628 </listitem>
7629   </varlistentry>
7630   <varlistentry id="cv-QT3_MOCHSUFFIX">
7631     <term>
7632       <envar>QT3_MOCHSUFFIX</envar>
7633     </term>
7634     <listitem><para>
7635 Default value is '&cv-link-CXXFILESUFFIX;'.
7636 Suffix for moc output files when source is a header.
7637 </para>
7638 <para>
7639 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCHSUFFIX.
7640 </para>
7641 </listitem>
7642   </varlistentry>
7643   <varlistentry id="cv-QT3_UIC">
7644     <term>
7645       <envar>QT3_UIC</envar>
7646     </term>
7647     <listitem><para>
7648 Default value is '&cv-link-QT3_BINPATH;<filename>/uic</filename>'.
7649 </para>
7650 <para>
7651 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UIC.
7652 </para>
7653 </listitem>
7654   </varlistentry>
7655   <varlistentry id="cv-QT3_UICCOM">
7656     <term>
7657       <envar>QT3_UICCOM</envar>
7658     </term>
7659     <listitem><para>
7660 Command to generate header files from <filename>.ui</filename> files.
7661 </para>
7662 <para>
7663 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICCOM.
7664 </para>
7665 </listitem>
7666   </varlistentry>
7667   <varlistentry id="cv-QT3_UICCOMSTR">
7668     <term>
7669       <envar>QT3_UICCOMSTR</envar>
7670     </term>
7671     <listitem><para>
7672 The string displayed when generating header files from <filename>.ui</filename> files.
7673 If this is not set, then &cv-link-QT3_UICCOM; (the command line) is displayed.
7674 </para>
7675 <para>
7676 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICCOMSTR.
7677 </para>
7678 </listitem>
7679   </varlistentry>
7680   <varlistentry id="cv-QT3_UICDECLFLAGS">
7681     <term>
7682       <envar>QT3_UICDECLFLAGS</envar>
7683     </term>
7684     <listitem><para>
7685 Default value is ''. These flags are passed to <command>uic</command>
7686 when creating a header file from a <filename>.ui</filename> file.
7687 </para>
7688 <para>
7689 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICDECLFLAGS.
7690 </para>
7691 </listitem>
7692   </varlistentry>
7693   <varlistentry id="cv-QT3_UICDECLPREFIX">
7694     <term>
7695       <envar>QT3_UICDECLPREFIX</envar>
7696     </term>
7697     <listitem><para>
7698 Default value is <literal>''</literal>.
7699 Prefix for <command>uic</command> generated header files.
7700 </para>
7701 <para>
7702 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICDECLPREFIX.
7703 </para>
7704 </listitem>
7705   </varlistentry>
7706   <varlistentry id="cv-QT3_UICDECLSUFFIX">
7707     <term>
7708       <envar>QT3_UICDECLSUFFIX</envar>
7709     </term>
7710     <listitem><para>
7711 Default value is <literal>'.h'</literal>.
7712 Suffix for <command>uic</command> generated header files.
7713 </para>
7714 <para>
7715 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICDECLSUFFIX.
7716 </para>
7717 </listitem>
7718   </varlistentry>
7719   <varlistentry id="cv-QT3_UICIMPLFLAGS">
7720     <term>
7721       <envar>QT3_UICIMPLFLAGS</envar>
7722     </term>
7723     <listitem><para>
7724 Default value is <literal>''</literal>.
7725 These flags are passed to <command>uic</command> when creating a C++
7726 file from a <filename>.ui</filename> file.
7727 </para>
7728 <para>
7729 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICIMPFLAGS.
7730 </para>
7731 </listitem>
7732   </varlistentry>
7733   <varlistentry id="cv-QT3_UICIMPLPREFIX">
7734     <term>
7735       <envar>QT3_UICIMPLPREFIX</envar>
7736     </term>
7737     <listitem><para>
7738 Default value is <literal>'uic_'</literal>.
7739 Prefix for uic generated implementation files.
7740 </para>
7741 <para>
7742 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICIMPLPREFIX.
7743 </para>
7744 </listitem>
7745   </varlistentry>
7746   <varlistentry id="cv-QT3_UICIMPLSUFFIX">
7747     <term>
7748       <envar>QT3_UICIMPLSUFFIX</envar>
7749     </term>
7750     <listitem><para>
7751 Default value is '&cv-link-CXXFILESUFFIX;'. Suffix for uic generated implementation
7752 files.
7753 </para>
7754 <para>
7755 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICIMPLSUFFIX.
7756 </para>
7757 </listitem>
7758   </varlistentry>
7759   <varlistentry id="cv-QT3_UISUFFIX">
7760     <term>
7761       <envar>QT3_UISUFFIX</envar>
7762     </term>
7763     <listitem><para>
7764 Default value is <literal>'.ui'</literal>.
7765 Suffix of designer input files.
7766 </para>
7767 <para>
7768 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UISUFFIX.
7769 </para>
7770 </listitem>
7771   </varlistentry>
7772   <varlistentry id="cv-QT3DIR">
7773     <term>
7774       <envar>QT3DIR</envar>
7775     </term>
7776     <listitem><para>
7777 The path to the Qt installation to build against.
7778 If not already set,
7779 &t-link-qt3; tool tries to obtain this from
7780 <varname>os.environ</varname>;
7781 if not found there, it tries to make a guess.
7782 </para>
7783 <para>
7784 <emphasis>Changed in 4.5.0</emphasis>: renamed from QTDIR.
7785 </para>
7786 </listitem>
7787   </varlistentry>
7788   <varlistentry id="cv-RANLIB">
7789     <term>
7790       <envar>RANLIB</envar>
7791     </term>
7792     <listitem><para>
7793 The archive indexer.
7794 </para>
7795 </listitem>
7796   </varlistentry>
7797   <varlistentry id="cv-RANLIBCOM">
7798     <term>
7799       <envar>RANLIBCOM</envar>
7800     </term>
7801     <listitem><para>
7802 The command line used to index a static library archive.
7803 </para>
7804 </listitem>
7805   </varlistentry>
7806   <varlistentry id="cv-RANLIBCOMSTR">
7807     <term>
7808       <envar>RANLIBCOMSTR</envar>
7809     </term>
7810     <listitem><para>
7811 The string displayed when a static library archive is indexed.
7812 If this is not set, then &cv-link-RANLIBCOM; (the command line) is displayed.
7813 </para>
7814
7815 <example_commands>
7816 env = Environment(RANLIBCOMSTR = "Indexing $TARGET")
7817 </example_commands>
7818 </listitem>
7819   </varlistentry>
7820   <varlistentry id="cv-RANLIBFLAGS">
7821     <term>
7822       <envar>RANLIBFLAGS</envar>
7823     </term>
7824     <listitem><para>
7825 General options passed to the archive indexer.
7826 </para>
7827 </listitem>
7828   </varlistentry>
7829   <varlistentry id="cv-RC">
7830     <term>
7831       <envar>RC</envar>
7832     </term>
7833     <listitem><para>
7834 The resource compiler used to build
7835 a &MSVC; resource file.
7836 </para>
7837 </listitem>
7838   </varlistentry>
7839   <varlistentry id="cv-RCCOM">
7840     <term>
7841       <envar>RCCOM</envar>
7842     </term>
7843     <listitem><para>
7844 The command line used to build
7845 a &MSVC; resource file.
7846 </para>
7847 </listitem>
7848   </varlistentry>
7849   <varlistentry id="cv-RCCOMSTR">
7850     <term>
7851       <envar>RCCOMSTR</envar>
7852     </term>
7853     <listitem><para>
7854 The string displayed when invoking the resource compiler
7855 to build a &MSVC; resource file.
7856 If this is not set, then &cv-link-RCCOM; (the command line) is displayed.
7857 </para>
7858 </listitem>
7859   </varlistentry>
7860   <varlistentry id="cv-RCFLAGS">
7861     <term>
7862       <envar>RCFLAGS</envar>
7863     </term>
7864     <listitem><para>
7865 The flags passed to the resource compiler by the &b-link-RES; builder.
7866 </para>
7867 </listitem>
7868   </varlistentry>
7869   <varlistentry id="cv-RCINCFLAGS">
7870     <term>
7871       <envar>RCINCFLAGS</envar>
7872     </term>
7873     <listitem><para>
7874 An automatically-generated &consvar;
7875 containing the command-line options
7876 for specifying directories to be searched
7877 by the resource compiler.
7878 The value of &cv-RCINCFLAGS; is created
7879 by respectively prepending and appending
7880 &cv-link-RCINCPREFIX; and &cv-link-RCINCSUFFIX;
7881 to the beginning and end
7882 of each directory in &cv-link-CPPPATH;.
7883 </para>
7884 </listitem>
7885   </varlistentry>
7886   <varlistentry id="cv-RCINCPREFIX">
7887     <term>
7888       <envar>RCINCPREFIX</envar>
7889     </term>
7890     <listitem><para>
7891 The prefix (flag) used to specify an include directory
7892 on the resource compiler command line.
7893 This will be prepended to the beginning of each directory
7894 in the &cv-link-CPPPATH; &consvar;
7895 when the &cv-link-RCINCFLAGS; variable is expanded.
7896 </para>
7897 </listitem>
7898   </varlistentry>
7899   <varlistentry id="cv-RCINCSUFFIX">
7900     <term>
7901       <envar>RCINCSUFFIX</envar>
7902     </term>
7903     <listitem><para>
7904 The suffix used to specify an include directory
7905 on the resource compiler command line.
7906 This will be appended to the end of each directory
7907 in the &cv-link-CPPPATH; &consvar;
7908 when the &cv-link-RCINCFLAGS; variable is expanded.
7909 </para>
7910 </listitem>
7911   </varlistentry>
7912   <varlistentry id="cv-RDirs">
7913     <term>
7914       <envar>RDirs</envar>
7915     </term>
7916     <listitem><para>
7917 A function that converts a string into a list of Dir instances by
7918 searching the repositories.
7919 </para>
7920 </listitem>
7921   </varlistentry>
7922   <varlistentry id="cv-REGSVR">
7923     <term>
7924       <envar>REGSVR</envar>
7925     </term>
7926     <listitem><para>
7927 The program used on Windows systems
7928 to register a newly-built DLL library
7929 whenever the &b-link-SharedLibrary; builder
7930 is passed a keyword argument of <literal>register=True</literal>.
7931 </para>
7932 </listitem>
7933   </varlistentry>
7934   <varlistentry id="cv-REGSVRCOM">
7935     <term>
7936       <envar>REGSVRCOM</envar>
7937     </term>
7938     <listitem><para>
7939 The command line used on Windows systems
7940 to register a newly-built DLL library
7941 whenever the &b-link-SharedLibrary; builder
7942 is passed a keyword argument of <literal>register=True</literal>.
7943 </para>
7944 </listitem>
7945   </varlistentry>
7946   <varlistentry id="cv-REGSVRCOMSTR">
7947     <term>
7948       <envar>REGSVRCOMSTR</envar>
7949     </term>
7950     <listitem><para>
7951 The string displayed when registering a newly-built DLL file.
7952 If this is not set, then &cv-link-REGSVRCOM; (the command line) is displayed.
7953 </para>
7954 </listitem>
7955   </varlistentry>
7956   <varlistentry id="cv-REGSVRFLAGS">
7957     <term>
7958       <envar>REGSVRFLAGS</envar>
7959     </term>
7960     <listitem><para>
7961 Flags passed to the DLL registration program
7962 on Windows systems when a newly-built DLL library is registered.
7963 By default,
7964 this includes the <option>/s</option>
7965 that prevents dialog boxes from popping up
7966 and requiring user attention.
7967 </para>
7968 </listitem>
7969   </varlistentry>
7970   <varlistentry id="cv-RMIC">
7971     <term>
7972       <envar>RMIC</envar>
7973     </term>
7974     <listitem><para>
7975 The Java RMI stub compiler.
7976 </para>
7977 </listitem>
7978   </varlistentry>
7979   <varlistentry id="cv-RMICCOM">
7980     <term>
7981       <envar>RMICCOM</envar>
7982     </term>
7983     <listitem><para>
7984 The command line used to compile stub
7985 and skeleton class files
7986 from Java classes that contain RMI implementations.
7987 Any options specified in the &cv-link-RMICFLAGS; construction variable
7988 are included on this command line.
7989 </para>
7990 </listitem>
7991   </varlistentry>
7992   <varlistentry id="cv-RMICCOMSTR">
7993     <term>
7994       <envar>RMICCOMSTR</envar>
7995     </term>
7996     <listitem><para>
7997 The string displayed when compiling
7998 stub and skeleton class files
7999 from Java classes that contain RMI implementations.
8000 If this is not set, then &cv-link-RMICCOM; (the command line) is displayed.
8001 </para>
8002
8003 <example_commands>
8004 env = Environment(
8005     RMICCOMSTR="Generating stub/skeleton class files $TARGETS from $SOURCES"
8006 )
8007 </example_commands>
8008 </listitem>
8009   </varlistentry>
8010   <varlistentry id="cv-RMICFLAGS">
8011     <term>
8012       <envar>RMICFLAGS</envar>
8013     </term>
8014     <listitem><para>
8015 General options passed to the Java RMI stub compiler.
8016 </para>
8017 </listitem>
8018   </varlistentry>
8019   <varlistentry id="cv-RPATH">
8020     <term>
8021       <envar>RPATH</envar>
8022     </term>
8023     <listitem><para>
8024 A list of paths to search for shared libraries when running programs.
8025 Currently only used in the GNU (gnulink),
8026 IRIX (sgilink) and Sun (sunlink) linkers.
8027 Ignored on platforms and toolchains that don't support it.
8028 Note that the paths added to RPATH
8029 are not transformed by
8030 &scons;
8031 in any way:  if you want an absolute
8032 path, you must make it absolute yourself.
8033 </para>
8034 </listitem>
8035   </varlistentry>
8036   <varlistentry id="cv-_RPATH">
8037     <term>
8038       <envar>_RPATH</envar>
8039     </term>
8040     <listitem><para>
8041 An automatically-generated construction variable
8042 containing the rpath flags to be used when linking
8043 a program with shared libraries.
8044 The value of &cv-_RPATH; is created
8045 by respectively prepending &cv-RPATHPREFIX; and appending &cv-RPATHSUFFIX;
8046 to the beginning and end
8047 of each directory in &cv-RPATH;.
8048 </para>
8049 </listitem>
8050   </varlistentry>
8051   <varlistentry id="cv-RPATHPREFIX">
8052     <term>
8053       <envar>RPATHPREFIX</envar>
8054     </term>
8055     <listitem><para>
8056 The prefix used to specify a directory to be searched for
8057 shared libraries when running programs.
8058 This will be prepended to the beginning of each directory
8059 in the &cv-RPATH; construction variable
8060 when the &cv-_RPATH; variable is automatically generated.
8061 </para>
8062 </listitem>
8063   </varlistentry>
8064   <varlistentry id="cv-RPATHSUFFIX">
8065     <term>
8066       <envar>RPATHSUFFIX</envar>
8067     </term>
8068     <listitem><para>
8069 The suffix used to specify a directory to be searched for
8070 shared libraries when running programs.
8071 This will be appended to the end of each directory
8072 in the &cv-RPATH; construction variable
8073 when the &cv-_RPATH; variable is automatically generated.
8074 </para>
8075 </listitem>
8076   </varlistentry>
8077   <varlistentry id="cv-RPCGEN">
8078     <term>
8079       <envar>RPCGEN</envar>
8080     </term>
8081     <listitem><para>
8082 The RPC protocol compiler.
8083 </para>
8084 </listitem>
8085   </varlistentry>
8086   <varlistentry id="cv-RPCGENCLIENTFLAGS">
8087     <term>
8088       <envar>RPCGENCLIENTFLAGS</envar>
8089     </term>
8090     <listitem><para>
8091 Options passed to the RPC protocol compiler
8092 when generating client side stubs.
8093 These are in addition to any flags specified in the
8094 &cv-link-RPCGENFLAGS;
8095 construction variable.
8096 </para>
8097 </listitem>
8098   </varlistentry>
8099   <varlistentry id="cv-RPCGENFLAGS">
8100     <term>
8101       <envar>RPCGENFLAGS</envar>
8102     </term>
8103     <listitem><para>
8104 General options passed to the RPC protocol compiler.
8105 </para>
8106 </listitem>
8107   </varlistentry>
8108   <varlistentry id="cv-RPCGENHEADERFLAGS">
8109     <term>
8110       <envar>RPCGENHEADERFLAGS</envar>
8111     </term>
8112     <listitem><para>
8113 Options passed to the RPC protocol compiler
8114 when generating a header file.
8115 These are in addition to any flags specified in the
8116 &cv-link-RPCGENFLAGS;
8117 construction variable.
8118 </para>
8119 </listitem>
8120   </varlistentry>
8121   <varlistentry id="cv-RPCGENSERVICEFLAGS">
8122     <term>
8123       <envar>RPCGENSERVICEFLAGS</envar>
8124     </term>
8125     <listitem><para>
8126 Options passed to the RPC protocol compiler
8127 when generating server side stubs.
8128 These are in addition to any flags specified in the
8129 &cv-link-RPCGENFLAGS;
8130 construction variable.
8131 </para>
8132 </listitem>
8133   </varlistentry>
8134   <varlistentry id="cv-RPCGENXDRFLAGS">
8135     <term>
8136       <envar>RPCGENXDRFLAGS</envar>
8137     </term>
8138     <listitem><para>
8139 Options passed to the RPC protocol compiler
8140 when generating XDR routines.
8141 These are in addition to any flags specified in the
8142 &cv-link-RPCGENFLAGS;
8143 construction variable.
8144 </para>
8145 </listitem>
8146   </varlistentry>
8147   <varlistentry id="cv-SCANNERS">
8148     <term>
8149       <envar>SCANNERS</envar>
8150     </term>
8151     <listitem><para>
8152 A list of the available implicit dependency scanners.
8153 New file scanners may be added by
8154 appending to this list,
8155 although the more flexible approach
8156 is to associate scanners
8157 with a specific Builder.
8158 See the manpage sections "Builder Objects"
8159 and "Scanner Objects"
8160 for more information.
8161 </para>
8162 </listitem>
8163   </varlistentry>
8164   <varlistentry id="cv-SCONS_HOME">
8165     <term>
8166       <envar>SCONS_HOME</envar>
8167     </term>
8168     <listitem><para>
8169         The (optional) path to the &SCons; library directory,
8170         initialized from the external environment. If set, this is
8171         used to construct a shorter and more efficient search path in
8172         the &cv-link-MSVSSCONS; command line executed from C++
8173         project files.
8174       </para>
8175     </listitem>
8176   </varlistentry>
8177   <varlistentry id="cv-SHCC">
8178     <term>
8179       <envar>SHCC</envar>
8180     </term>
8181     <listitem><para>
8182 The C compiler used for generating shared-library objects.
8183 See also &cv-link-CC; for compiling to static objects.
8184 </para>
8185 </listitem>
8186   </varlistentry>
8187   <varlistentry id="cv-SHCCCOM">
8188     <term>
8189       <envar>SHCCCOM</envar>
8190     </term>
8191     <listitem><para>
8192 The command line used to compile a C source file
8193 to a shared-library object file.
8194 Any options specified in the &cv-link-SHCFLAGS;,
8195 &cv-link-SHCCFLAGS; and
8196 &cv-link-CPPFLAGS; construction variables
8197 are included on this command line.
8198 See also &cv-link-CCCOM; for compiling to static objects.
8199 </para>
8200 </listitem>
8201   </varlistentry>
8202   <varlistentry id="cv-SHCCCOMSTR">
8203     <term>
8204       <envar>SHCCCOMSTR</envar>
8205     </term>
8206     <listitem><para>
8207 If set, the string displayed when a C source file
8208 is compiled to a shared object file.
8209 If not set, then &cv-link-SHCCCOM; (the command line) is displayed.
8210 See also &cv-link-CCCOMSTR; for compiling to static objects.
8211 </para>
8212
8213 <example_commands>
8214 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
8215 </example_commands>
8216 </listitem>
8217   </varlistentry>
8218   <varlistentry id="cv-SHCCFLAGS">
8219     <term>
8220       <envar>SHCCFLAGS</envar>
8221     </term>
8222     <listitem><para>
8223 Options that are passed to the C and C++ compilers
8224 to generate shared-library objects.
8225 See also &cv-link-CCFLAGS; for compiling to static objects.
8226 </para>
8227 </listitem>
8228   </varlistentry>
8229   <varlistentry id="cv-SHCFLAGS">
8230     <term>
8231       <envar>SHCFLAGS</envar>
8232     </term>
8233     <listitem><para>
8234 Options that are passed to the C compiler (only; not C++)
8235 to generate shared-library objects.
8236 See also &cv-link-CFLAGS; for compiling to static objects.
8237 </para>
8238 </listitem>
8239   </varlistentry>
8240   <varlistentry id="cv-SHCXX">
8241     <term>
8242       <envar>SHCXX</envar>
8243     </term>
8244     <listitem><para>
8245 The C++ compiler used for generating shared-library objects.
8246 See also &cv-link-CXX; for compiling to static objects.
8247 </para>
8248 </listitem>
8249   </varlistentry>
8250   <varlistentry id="cv-SHCXXCOM">
8251     <term>
8252       <envar>SHCXXCOM</envar>
8253     </term>
8254     <listitem><para>
8255 The command line used to compile a C++ source file
8256 to a shared-library object file.
8257 Any options specified in the &cv-link-SHCXXFLAGS; and
8258 &cv-link-CPPFLAGS; construction variables
8259 are included on this command line.
8260 See also &cv-link-CXXCOM; for compiling to static objects.
8261 </para>
8262 </listitem>
8263   </varlistentry>
8264   <varlistentry id="cv-SHCXXCOMSTR">
8265     <term>
8266       <envar>SHCXXCOMSTR</envar>
8267     </term>
8268     <listitem><para>
8269 If set, the string displayed when a C++ source file
8270 is compiled to a shared object file.
8271 If not set, then &cv-link-SHCXXCOM; (the command line) is displayed.
8272 See also &cv-link-CXXCOMSTR; for compiling to static objects.
8273 </para>
8274
8275 <example_commands>
8276 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
8277 </example_commands>
8278 </listitem>
8279   </varlistentry>
8280   <varlistentry id="cv-SHCXXFLAGS">
8281     <term>
8282       <envar>SHCXXFLAGS</envar>
8283     </term>
8284     <listitem><para>
8285 Options that are passed to the C++ compiler
8286 to generate shared-library objects.
8287 See also &cv-link-CXXFLAGS; for compiling to static objects.
8288 </para>
8289 </listitem>
8290   </varlistentry>
8291   <varlistentry id="cv-SHDC">
8292     <term>
8293       <envar>SHDC</envar>
8294     </term>
8295     <listitem><para>
8296 The name of the compiler to use when compiling D source
8297 destined to be in a shared objects.
8298 See also &cv-link-DC; for compiling to static objects.
8299 </para>
8300 </listitem>
8301   </varlistentry>
8302   <varlistentry id="cv-SHDCOM">
8303     <term>
8304       <envar>SHDCOM</envar>
8305     </term>
8306     <listitem><para>
8307 The command line to use when compiling code to be part of shared objects.
8308 See also &cv-link-DCOM; for compiling to static objects.
8309 </para>
8310 </listitem>
8311   </varlistentry>
8312   <varlistentry id="cv-SHDCOMSTR">
8313     <term>
8314       <envar>SHDCOMSTR</envar>
8315     </term>
8316     <listitem><para>
8317 If set, the string displayed when a D source file
8318 is compiled to a (shared) object file.
8319 If not set, then &cv-link-SHDCOM; (the command line) is displayed.
8320 See also &cv-link-DCOMSTR; for compiling to static objects.
8321 </para>
8322 </listitem>
8323   </varlistentry>
8324   <varlistentry id="cv-SHDLIBVERSIONFLAGS">
8325     <term>
8326       <envar>SHDLIBVERSIONFLAGS</envar>
8327     </term>
8328     <listitem><para>
8329 Extra flags added to &cv-link-SHDLINKCOM; when building versioned
8330 &b-link-SharedLibrary;. These flags are only used when &cv-link-SHLIBVERSION; is
8331 set.
8332 </para>
8333 </listitem>
8334   </varlistentry>
8335   <varlistentry id="cv-SHDLINK">
8336     <term>
8337       <envar>SHDLINK</envar>
8338     </term>
8339     <listitem><para>
8340 The linker to use when creating shared objects for code bases
8341 include D sources.
8342 See also &cv-link-DLINK; for linking static objects.
8343 </para>
8344 </listitem>
8345   </varlistentry>
8346   <varlistentry id="cv-SHDLINKCOM">
8347     <term>
8348       <envar>SHDLINKCOM</envar>
8349     </term>
8350     <listitem><para>
8351 The command line to use when generating shared objects.
8352 See also &cv-link-DLINKCOM; for linking static objects.
8353 </para>
8354 </listitem>
8355   </varlistentry>
8356   <varlistentry id="cv-SHDLINKFLAGS">
8357     <term>
8358       <envar>SHDLINKFLAGS</envar>
8359     </term>
8360     <listitem><para>
8361 The list of flags to use when generating a shared object.
8362 See also &cv-link-DLINKFLAGS; for linking static objects.
8363 </para>
8364 </listitem>
8365   </varlistentry>
8366   <varlistentry id="cv-SHELL">
8367     <term>
8368       <envar>SHELL</envar>
8369     </term>
8370     <listitem><para>
8371 A string naming the shell program that will be passed to the
8372 &cv-SPAWN;
8373 function.
8374 See the
8375 &cv-SPAWN;
8376 construction variable for more information.
8377 </para>
8378 </listitem>
8379   </varlistentry>
8380   <varlistentry id="cv-SHELL_ENV_GENERATORS">
8381     <term>
8382       <envar>SHELL_ENV_GENERATORS</envar>
8383     </term>
8384     <listitem><para>
8385 A hook allowing the execution environment to be modified prior
8386 to the actual execution of a command line from an action
8387 via the spawner function defined by &cv-link-SPAWN;.
8388 Allows substitution based on targets and sources,
8389 as well as values from the &consenv;,
8390 adding extra environment variables, etc.
8391     </para>
8392
8393     <para>
8394 The value must be a list (or other iterable)
8395 of functions which each generate or
8396 alter the execution environment dictionary.
8397 The first function will be passed a copy of the initial execution environment
8398 (&cv-link-ENV; in the current &consenv;);
8399 the dictionary returned by that function is passed to the next,
8400 until the iterable is exhausted and the result returned
8401 for use by the command spawner.
8402 The original execution environment is not modified.
8403     </para>
8404
8405     <para>
8406 Each function provided in &cv-SHELL_ENV_GENERATORS; must accept four
8407 arguments and return a dictionary:
8408 <varname>env</varname> is the &consenv; for this action;
8409 <varname>target</varname> is the list of targets associated with this action;
8410 <varname>source</varname> is the list of sources associated with this action;
8411 and <varname>shell_env</varname> is the current dictionary after iterating
8412 any previous &cv-SHELL_ENV_GENERATORS; functions
8413 (this can be compared to the original execution environment,
8414 which is available as <literal>env['ENV']</literal>, to detect any changes).
8415     </para>
8416
8417     <para>Example:</para>
8418     <example_commands>
8419 def custom_shell_env(env, target, source, shell_env):
8420     """customize shell_env if desired"""
8421     if str(target[0]) == 'special_target':
8422         shell_env['SPECIAL_VAR'] = env.subst('SOME_VAR', target=target, source=source)
8423     return shell_env
8424
8425 env["SHELL_ENV_GENERATORS"] = [custom_shell_env]
8426     </example_commands>
8427
8428   <para><emphasis>Available since 4.4</emphasis></para>
8429   </listitem>
8430   </varlistentry>
8431   <varlistentry id="cv-SHF03">
8432     <term>
8433       <envar>SHF03</envar>
8434     </term>
8435     <listitem><para>
8436 The Fortran 03 compiler used for generating shared-library objects.
8437 You should normally set the &cv-link-SHFORTRAN; variable,
8438 which specifies the default Fortran compiler
8439 for all Fortran versions.
8440 You only need to set &cv-link-SHF03; if you need to use a specific compiler
8441 or compiler version for Fortran 03 files.
8442 </para>
8443 </listitem>
8444   </varlistentry>
8445   <varlistentry id="cv-SHF03COM">
8446     <term>
8447       <envar>SHF03COM</envar>
8448     </term>
8449     <listitem><para>
8450 The command line used to compile a Fortran 03 source file
8451 to a shared-library object file.
8452 You only need to set &cv-link-SHF03COM; if you need to use a specific
8453 command line for Fortran 03 files.
8454 You should normally set the &cv-link-SHFORTRANCOM; variable,
8455 which specifies the default command line
8456 for all Fortran versions.
8457 </para>
8458 </listitem>
8459   </varlistentry>
8460   <varlistentry id="cv-SHF03COMSTR">
8461     <term>
8462       <envar>SHF03COMSTR</envar>
8463     </term>
8464     <listitem><para>
8465 If set, the string displayed when a Fortran 03 source file
8466 is compiled to a shared-library object file.
8467 If not set, then &cv-link-SHF03COM; or &cv-link-SHFORTRANCOM;
8468 (the command line) is displayed.
8469 </para>
8470 </listitem>
8471   </varlistentry>
8472   <varlistentry id="cv-SHF03FLAGS">
8473     <term>
8474       <envar>SHF03FLAGS</envar>
8475     </term>
8476     <listitem><para>
8477 Options that are passed to the Fortran 03 compiler
8478 to generated shared-library objects.
8479 You only need to set &cv-link-SHF03FLAGS; if you need to define specific
8480 user options for Fortran 03 files.
8481 You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
8482 which specifies the user-specified options
8483 passed to the default Fortran compiler
8484 for all Fortran versions.
8485 </para>
8486 </listitem>
8487   </varlistentry>
8488   <varlistentry id="cv-SHF03PPCOM">
8489     <term>
8490       <envar>SHF03PPCOM</envar>
8491     </term>
8492     <listitem><para>
8493 The command line used to compile a Fortran 03 source file to a
8494 shared-library object file
8495 after first running the file through the C preprocessor.
8496 Any options specified in the &cv-link-SHF03FLAGS; and &cv-link-CPPFLAGS; construction variables
8497 are included on this command line.
8498 You only need to set &cv-link-SHF03PPCOM; if you need to use a specific
8499 C-preprocessor command line for Fortran 03 files.
8500 You should normally set the &cv-link-SHFORTRANPPCOM; variable,
8501 which specifies the default C-preprocessor command line
8502 for all Fortran versions.
8503 </para>
8504 </listitem>
8505   </varlistentry>
8506   <varlistentry id="cv-SHF03PPCOMSTR">
8507     <term>
8508       <envar>SHF03PPCOMSTR</envar>
8509     </term>
8510     <listitem><para>
8511 If set, the string displayed when a Fortran 03 source file
8512 is compiled to a shared-library object file
8513 after first running the file through the C preprocessor.
8514 If not set, then &cv-link-SHF03PPCOM; or &cv-link-SHFORTRANPPCOM;
8515 (the command line) is displayed.
8516 </para>
8517 </listitem>
8518   </varlistentry>
8519   <varlistentry id="cv-SHF08">
8520     <term>
8521       <envar>SHF08</envar>
8522     </term>
8523     <listitem><para>
8524 The Fortran 08 compiler used for generating shared-library objects.
8525 You should normally set the &cv-link-SHFORTRAN; variable,
8526 which specifies the default Fortran compiler
8527 for all Fortran versions.
8528 You only need to set &cv-link-SHF08; if you need to use a specific compiler
8529 or compiler version for Fortran 08 files.
8530 </para>
8531 </listitem>
8532   </varlistentry>
8533   <varlistentry id="cv-SHF08COM">
8534     <term>
8535       <envar>SHF08COM</envar>
8536     </term>
8537     <listitem><para>
8538 The command line used to compile a Fortran 08 source file
8539 to a shared-library object file.
8540 You only need to set &cv-link-SHF08COM; if you need to use a specific
8541 command line for Fortran 08 files.
8542 You should normally set the &cv-link-SHFORTRANCOM; variable,
8543 which specifies the default command line
8544 for all Fortran versions.
8545 </para>
8546 </listitem>
8547   </varlistentry>
8548   <varlistentry id="cv-SHF08COMSTR">
8549     <term>
8550       <envar>SHF08COMSTR</envar>
8551     </term>
8552     <listitem><para>
8553 If set, the string displayed when a Fortran 08 source file
8554 is compiled to a shared-library object file.
8555 If not set, then &cv-link-SHF08COM; or &cv-link-SHFORTRANCOM;
8556 (the command line) is displayed.
8557 </para>
8558 </listitem>
8559   </varlistentry>
8560   <varlistentry id="cv-SHF08FLAGS">
8561     <term>
8562       <envar>SHF08FLAGS</envar>
8563     </term>
8564     <listitem><para>
8565 Options that are passed to the Fortran 08 compiler
8566 to generated shared-library objects.
8567 You only need to set &cv-link-SHF08FLAGS; if you need to define specific
8568 user options for Fortran 08 files.
8569 You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
8570 which specifies the user-specified options
8571 passed to the default Fortran compiler
8572 for all Fortran versions.
8573 </para>
8574 </listitem>
8575   </varlistentry>
8576   <varlistentry id="cv-SHF08PPCOM">
8577     <term>
8578       <envar>SHF08PPCOM</envar>
8579     </term>
8580     <listitem><para>
8581 The command line used to compile a Fortran 08 source file to a
8582 shared-library object file
8583 after first running the file through the C preprocessor.
8584 Any options specified in the &cv-link-SHF08FLAGS; and &cv-link-CPPFLAGS; construction variables
8585 are included on this command line.
8586 You only need to set &cv-link-SHF08PPCOM; if you need to use a specific
8587 C-preprocessor command line for Fortran 08 files.
8588 You should normally set the &cv-link-SHFORTRANPPCOM; variable,
8589 which specifies the default C-preprocessor command line
8590 for all Fortran versions.
8591 </para>
8592 </listitem>
8593   </varlistentry>
8594   <varlistentry id="cv-SHF08PPCOMSTR">
8595     <term>
8596       <envar>SHF08PPCOMSTR</envar>
8597     </term>
8598     <listitem><para>
8599 If set, the string displayed when a Fortran 08 source file
8600 is compiled to a shared-library object file
8601 after first running the file through the C preprocessor.
8602 If not set, then &cv-link-SHF08PPCOM; or &cv-link-SHFORTRANPPCOM;
8603 (the command line) is displayed.
8604 </para>
8605 </listitem>
8606   </varlistentry>
8607   <varlistentry id="cv-SHF77">
8608     <term>
8609       <envar>SHF77</envar>
8610     </term>
8611     <listitem><para>
8612 The Fortran 77 compiler used for generating shared-library objects.
8613 You should normally set the &cv-link-SHFORTRAN; variable,
8614 which specifies the default Fortran compiler
8615 for all Fortran versions.
8616 You only need to set &cv-link-SHF77; if you need to use a specific compiler
8617 or compiler version for Fortran 77 files.
8618 </para>
8619 </listitem>
8620   </varlistentry>
8621   <varlistentry id="cv-SHF77COM">
8622     <term>
8623       <envar>SHF77COM</envar>
8624     </term>
8625     <listitem><para>
8626 The command line used to compile a Fortran 77 source file
8627 to a shared-library object file.
8628 You only need to set &cv-link-SHF77COM; if you need to use a specific
8629 command line for Fortran 77 files.
8630 You should normally set the &cv-link-SHFORTRANCOM; variable,
8631 which specifies the default command line
8632 for all Fortran versions.
8633 </para>
8634 </listitem>
8635   </varlistentry>
8636   <varlistentry id="cv-SHF77COMSTR">
8637     <term>
8638       <envar>SHF77COMSTR</envar>
8639     </term>
8640     <listitem><para>
8641 If set, the string displayed when a Fortran 77 source file
8642 is compiled to a shared-library object file.
8643 If not set, then &cv-link-SHF77COM; or &cv-link-SHFORTRANCOM;
8644 (the command line) is displayed.
8645 </para>
8646 </listitem>
8647   </varlistentry>
8648   <varlistentry id="cv-SHF77FLAGS">
8649     <term>
8650       <envar>SHF77FLAGS</envar>
8651     </term>
8652     <listitem><para>
8653 Options that are passed to the Fortran 77 compiler
8654 to generated shared-library objects.
8655 You only need to set &cv-link-SHF77FLAGS; if you need to define specific
8656 user options for Fortran 77 files.
8657 You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
8658 which specifies the user-specified options
8659 passed to the default Fortran compiler
8660 for all Fortran versions.
8661 </para>
8662 </listitem>
8663   </varlistentry>
8664   <varlistentry id="cv-SHF77PPCOM">
8665     <term>
8666       <envar>SHF77PPCOM</envar>
8667     </term>
8668     <listitem><para>
8669 The command line used to compile a Fortran 77 source file to a
8670 shared-library object file
8671 after first running the file through the C preprocessor.
8672 Any options specified in the &cv-link-SHF77FLAGS; and &cv-link-CPPFLAGS; construction variables
8673 are included on this command line.
8674 You only need to set &cv-link-SHF77PPCOM; if you need to use a specific
8675 C-preprocessor command line for Fortran 77 files.
8676 You should normally set the &cv-link-SHFORTRANPPCOM; variable,
8677 which specifies the default C-preprocessor command line
8678 for all Fortran versions.
8679 </para>
8680 </listitem>
8681   </varlistentry>
8682   <varlistentry id="cv-SHF77PPCOMSTR">
8683     <term>
8684       <envar>SHF77PPCOMSTR</envar>
8685     </term>
8686     <listitem><para>
8687 If set, the string displayed when a Fortran 77 source file
8688 is compiled to a shared-library object file
8689 after first running the file through the C preprocessor.
8690 If not set, then &cv-link-SHF77PPCOM; or &cv-link-SHFORTRANPPCOM;
8691 (the command line) is displayed.
8692 </para>
8693 </listitem>
8694   </varlistentry>
8695   <varlistentry id="cv-SHF90">
8696     <term>
8697       <envar>SHF90</envar>
8698     </term>
8699     <listitem><para>
8700 The Fortran 90 compiler used for generating shared-library objects.
8701 You should normally set the &cv-link-SHFORTRAN; variable,
8702 which specifies the default Fortran compiler
8703 for all Fortran versions.
8704 You only need to set &cv-link-SHF90; if you need to use a specific compiler
8705 or compiler version for Fortran 90 files.
8706 </para>
8707 </listitem>
8708   </varlistentry>
8709   <varlistentry id="cv-SHF90COM">
8710     <term>
8711       <envar>SHF90COM</envar>
8712     </term>
8713     <listitem><para>
8714 The command line used to compile a Fortran 90 source file
8715 to a shared-library object file.
8716 You only need to set &cv-link-SHF90COM; if you need to use a specific
8717 command line for Fortran 90 files.
8718 You should normally set the &cv-link-SHFORTRANCOM; variable,
8719 which specifies the default command line
8720 for all Fortran versions.
8721 </para>
8722 </listitem>
8723   </varlistentry>
8724   <varlistentry id="cv-SHF90COMSTR">
8725     <term>
8726       <envar>SHF90COMSTR</envar>
8727     </term>
8728     <listitem><para>
8729 If set, the string displayed when a Fortran 90 source file
8730 is compiled to a shared-library object file.
8731 If not set, then &cv-link-SHF90COM; or &cv-link-SHFORTRANCOM;
8732 (the command line) is displayed.
8733 </para>
8734 </listitem>
8735   </varlistentry>
8736   <varlistentry id="cv-SHF90FLAGS">
8737     <term>
8738       <envar>SHF90FLAGS</envar>
8739     </term>
8740     <listitem><para>
8741 Options that are passed to the Fortran 90 compiler
8742 to generated shared-library objects.
8743 You only need to set &cv-link-SHF90FLAGS; if you need to define specific
8744 user options for Fortran 90 files.
8745 You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
8746 which specifies the user-specified options
8747 passed to the default Fortran compiler
8748 for all Fortran versions.
8749 </para>
8750 </listitem>
8751   </varlistentry>
8752   <varlistentry id="cv-SHF90PPCOM">
8753     <term>
8754       <envar>SHF90PPCOM</envar>
8755     </term>
8756     <listitem><para>
8757 The command line used to compile a Fortran 90 source file to a
8758 shared-library object file
8759 after first running the file through the C preprocessor.
8760 Any options specified in the &cv-link-SHF90FLAGS; and &cv-link-CPPFLAGS; construction variables
8761 are included on this command line.
8762 You only need to set &cv-link-SHF90PPCOM; if you need to use a specific
8763 C-preprocessor command line for Fortran 90 files.
8764 You should normally set the &cv-link-SHFORTRANPPCOM; variable,
8765 which specifies the default C-preprocessor command line
8766 for all Fortran versions.
8767 </para>
8768 </listitem>
8769   </varlistentry>
8770   <varlistentry id="cv-SHF90PPCOMSTR">
8771     <term>
8772       <envar>SHF90PPCOMSTR</envar>
8773     </term>
8774     <listitem><para>
8775 If set, the string displayed when a Fortran 90 source file
8776 is compiled to a shared-library object file
8777 after first running the file through the C preprocessor.
8778 If not set, then &cv-link-SHF90PPCOM; or &cv-link-SHFORTRANPPCOM;
8779 (the command line) is displayed.
8780 </para>
8781 </listitem>
8782   </varlistentry>
8783   <varlistentry id="cv-SHF95">
8784     <term>
8785       <envar>SHF95</envar>
8786     </term>
8787     <listitem><para>
8788 The Fortran 95 compiler used for generating shared-library objects.
8789 You should normally set the &cv-link-SHFORTRAN; variable,
8790 which specifies the default Fortran compiler
8791 for all Fortran versions.
8792 You only need to set &cv-link-SHF95; if you need to use a specific compiler
8793 or compiler version for Fortran 95 files.
8794 </para>
8795 </listitem>
8796   </varlistentry>
8797   <varlistentry id="cv-SHF95COM">
8798     <term>
8799       <envar>SHF95COM</envar>
8800     </term>
8801     <listitem><para>
8802 The command line used to compile a Fortran 95 source file
8803 to a shared-library object file.
8804 You only need to set &cv-link-SHF95COM; if you need to use a specific
8805 command line for Fortran 95 files.
8806 You should normally set the &cv-link-SHFORTRANCOM; variable,
8807 which specifies the default command line
8808 for all Fortran versions.
8809 </para>
8810 </listitem>
8811   </varlistentry>
8812   <varlistentry id="cv-SHF95COMSTR">
8813     <term>
8814       <envar>SHF95COMSTR</envar>
8815     </term>
8816     <listitem><para>
8817 If set, the string displayed when a Fortran 95 source file
8818 is compiled to a shared-library object file.
8819 If not set, then &cv-link-SHF95COM; or &cv-link-SHFORTRANCOM;
8820 (the command line) is displayed.
8821 </para>
8822 </listitem>
8823   </varlistentry>
8824   <varlistentry id="cv-SHF95FLAGS">
8825     <term>
8826       <envar>SHF95FLAGS</envar>
8827     </term>
8828     <listitem><para>
8829 Options that are passed to the Fortran 95 compiler
8830 to generated shared-library objects.
8831 You only need to set &cv-link-SHF95FLAGS; if you need to define specific
8832 user options for Fortran 95 files.
8833 You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
8834 which specifies the user-specified options
8835 passed to the default Fortran compiler
8836 for all Fortran versions.
8837 </para>
8838 </listitem>
8839   </varlistentry>
8840   <varlistentry id="cv-SHF95PPCOM">
8841     <term>
8842       <envar>SHF95PPCOM</envar>
8843     </term>
8844     <listitem><para>
8845 The command line used to compile a Fortran 95 source file to a
8846 shared-library object file
8847 after first running the file through the C preprocessor.
8848 Any options specified in the &cv-link-SHF95FLAGS; and &cv-link-CPPFLAGS; construction variables
8849 are included on this command line.
8850 You only need to set &cv-link-SHF95PPCOM; if you need to use a specific
8851 C-preprocessor command line for Fortran 95 files.
8852 You should normally set the &cv-link-SHFORTRANPPCOM; variable,
8853 which specifies the default C-preprocessor command line
8854 for all Fortran versions.
8855 </para>
8856 </listitem>
8857   </varlistentry>
8858   <varlistentry id="cv-SHF95PPCOMSTR">
8859     <term>
8860       <envar>SHF95PPCOMSTR</envar>
8861     </term>
8862     <listitem><para>
8863 If set, the string displayed when a Fortran 95 source file
8864 is compiled to a shared-library object file
8865 after first running the file through the C preprocessor.
8866 If not set, then &cv-link-SHF95PPCOM; or &cv-link-SHFORTRANPPCOM;
8867 (the command line) is displayed.
8868 </para>
8869 </listitem>
8870   </varlistentry>
8871   <varlistentry id="cv-SHFORTRAN">
8872     <term>
8873       <envar>SHFORTRAN</envar>
8874     </term>
8875     <listitem><para>
8876 The default Fortran compiler used for generating shared-library objects.
8877 </para>
8878 </listitem>
8879   </varlistentry>
8880   <varlistentry id="cv-SHFORTRANCOM">
8881     <term>
8882       <envar>SHFORTRANCOM</envar>
8883     </term>
8884     <listitem><para>
8885 The command line used to compile a Fortran source file
8886 to a shared-library object file.
8887 By default, any options specified
8888 in the &cv-link-SHFORTRANFLAGS;,
8889 &cv-link-_FORTRANMODFLAG;, and
8890 &cv-link-_FORTRANINCFLAGS;
8891 &consvars; are included on this command line.
8892 See also &cv-link-FORTRANCOM;.
8893 </para>
8894 </listitem>
8895   </varlistentry>
8896   <varlistentry id="cv-SHFORTRANCOMSTR">
8897     <term>
8898       <envar>SHFORTRANCOMSTR</envar>
8899     </term>
8900     <listitem><para>
8901 If set, the string displayed when a Fortran source file
8902 is compiled to a shared-library object file.
8903 If not set, then &cv-link-SHFORTRANCOM;
8904 (the command line) is displayed.
8905 </para>
8906 </listitem>
8907   </varlistentry>
8908   <varlistentry id="cv-SHFORTRANFLAGS">
8909     <term>
8910       <envar>SHFORTRANFLAGS</envar>
8911     </term>
8912     <listitem><para>
8913 Options that are passed to the Fortran compiler
8914 to generate shared-library objects.
8915 </para>
8916 </listitem>
8917   </varlistentry>
8918   <varlistentry id="cv-SHFORTRANPPCOM">
8919     <term>
8920       <envar>SHFORTRANPPCOM</envar>
8921     </term>
8922     <listitem><para>
8923 The command line used to compile a Fortran source file to a
8924 shared-library object file
8925 after first running the file through the C preprocessor.
8926 By default, any options specified in the &cv-link-SHFORTRANFLAGS;,
8927 &cv-link-CPPFLAGS;,
8928 &cv-link-_CPPDEFFLAGS;,
8929 &cv-link-_FORTRANMODFLAG;, and
8930 &cv-link-_FORTRANINCFLAGS;
8931 &consvars; are included on this command line.
8932 See also &cv-link-SHFORTRANCOM;.
8933 </para>
8934 </listitem>
8935   </varlistentry>
8936   <varlistentry id="cv-SHFORTRANPPCOMSTR">
8937     <term>
8938       <envar>SHFORTRANPPCOMSTR</envar>
8939     </term>
8940     <listitem><para>
8941 If set, the string displayed when a Fortran source file
8942 is compiled to a shared-library object file
8943 after first running the file through the C preprocessor.
8944 If not set, then &cv-link-SHFORTRANPPCOM;
8945 (the command line) is displayed.
8946 </para>
8947 </listitem>
8948   </varlistentry>
8949   <varlistentry id="cv-SHLIBEMITTER">
8950     <term>
8951       <envar>SHLIBEMITTER</envar>
8952     </term>
8953     <listitem><para>
8954 Contains the emitter specification for the
8955 &b-link-SharedLibrary; builder.
8956 The manpage section "Builder Objects" contains
8957 general information on specifying emitters.
8958 </para>
8959 </listitem>
8960   </varlistentry>
8961   <varlistentry id="cv-SHLIBNOVERSIONSYMLINKS">
8962     <term>
8963       <envar>SHLIBNOVERSIONSYMLINKS</envar>
8964     </term>
8965     <listitem><para>
8966 Instructs the &b-link-SharedLibrary; builder to not create symlinks for versioned
8967 shared libraries.
8968 </para>
8969 </listitem>
8970   </varlistentry>
8971   <varlistentry id="cv-SHLIBPREFIX">
8972     <term>
8973       <envar>SHLIBPREFIX</envar>
8974     </term>
8975     <listitem><para>
8976 The prefix used for shared library file names.
8977 </para>
8978 </listitem>
8979   </varlistentry>
8980   <varlistentry id="cv-_SHLIBSONAME">
8981     <term>
8982       <envar>_SHLIBSONAME</envar>
8983     </term>
8984     <listitem><para>
8985 A macro that automatically generates shared library's SONAME based on $TARGET,
8986 $SHLIBVERSION and $SHLIBSUFFIX. Used by &b-link-SharedLibrary; builder when
8987 the linker tool supports SONAME (e.g. &t-link-gnulink;).
8988 </para>
8989 </listitem>
8990   </varlistentry>
8991   <varlistentry id="cv-SHLIBSUFFIX">
8992     <term>
8993       <envar>SHLIBSUFFIX</envar>
8994     </term>
8995     <listitem><para>
8996 The suffix used for shared library file names.
8997 </para>
8998 </listitem>
8999   </varlistentry>
9000   <varlistentry id="cv-SHLIBVERSION">
9001     <term>
9002       <envar>SHLIBVERSION</envar>
9003     </term>
9004     <listitem><para>
9005 When this &consvar; is defined, a versioned shared library
9006 is created by the &b-link-SharedLibrary; builder. This activates the
9007 &cv-link-_SHLIBVERSIONFLAGS; and thus modifies the &cv-link-SHLINKCOM; as
9008 required, adds the version number to the library name, and creates the symlinks
9009 that are needed.  &cv-link-SHLIBVERSION; versions should exist as alpha-numeric,
9010 decimal-delimited values as defined by the regular expression "\w+[\.\w+]*".
9011 Example &cv-link-SHLIBVERSION; values include '1', '1.2.3', and '1.2.gitaa412c8b'.
9012 </para>
9013 </listitem>
9014   </varlistentry>
9015   <varlistentry id="cv-_SHLIBVERSIONFLAGS">
9016     <term>
9017       <envar>_SHLIBVERSIONFLAGS</envar>
9018     </term>
9019     <listitem><para>
9020 This macro automatically introduces extra flags to &cv-link-SHLINKCOM; when
9021 building versioned &b-link-SharedLibrary; (that is when &cv-link-SHLIBVERSION;
9022 is set). <literal>_SHLIBVERSIONFLAGS</literal> usually adds &cv-link-SHLIBVERSIONFLAGS;
9023 and some extra dynamically generated options (such as
9024 <literal>-Wl,-soname=$_SHLIBSONAME</literal>. It is unused by "plain"
9025 (unversioned) shared libraries.
9026 </para>
9027 </listitem>
9028   </varlistentry>
9029   <varlistentry id="cv-SHLIBVERSIONFLAGS">
9030     <term>
9031       <envar>SHLIBVERSIONFLAGS</envar>
9032     </term>
9033     <listitem><para>
9034 Extra flags added to &cv-link-SHLINKCOM; when building versioned
9035 &b-link-SharedLibrary;. These flags are only used when &cv-link-SHLIBVERSION; is
9036 set.
9037 </para>
9038 </listitem>
9039   </varlistentry>
9040   <varlistentry id="cv-SHLINK">
9041     <term>
9042       <envar>SHLINK</envar>
9043     </term>
9044     <listitem><para>
9045 The linker for programs that use shared libraries.
9046 See also &cv-link-LINK; for linking static objects.
9047 </para>
9048 <para>
9049 On POSIX systems (those using the &t-link-link; tool),
9050 you should normally not change this value as it defaults
9051 to a "smart" linker tool which selects a compiler
9052 driver matching the type of source files in use.
9053 So for example, if you set &cv-link-SHCXX; to a specific
9054 compiler name, and are compiling C++ sources,
9055 the smartlink function will automatically select the same compiler
9056 for linking.
9057 </para>
9058 </listitem>
9059   </varlistentry>
9060   <varlistentry id="cv-SHLINKCOM">
9061     <term>
9062       <envar>SHLINKCOM</envar>
9063     </term>
9064     <listitem><para>
9065 The command line used to link programs using shared libraries.
9066 See also &cv-link-LINKCOM; for linking static objects.
9067 </para>
9068 </listitem>
9069   </varlistentry>
9070   <varlistentry id="cv-SHLINKCOMSTR">
9071     <term>
9072       <envar>SHLINKCOMSTR</envar>
9073     </term>
9074     <listitem><para>
9075 The string displayed when programs using shared libraries are linked.
9076 If this is not set, then &cv-link-SHLINKCOM; (the command line) is displayed.
9077 See also &cv-link-LINKCOMSTR;  for linking static objects.
9078 </para>
9079
9080 <example_commands>
9081 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
9082 </example_commands>
9083 </listitem>
9084   </varlistentry>
9085   <varlistentry id="cv-SHLINKFLAGS">
9086     <term>
9087       <envar>SHLINKFLAGS</envar>
9088     </term>
9089     <listitem><para>
9090 General user options passed to the linker for programs using shared libraries.
9091 Note that this variable should
9092 <emphasis>not</emphasis>
9093 contain
9094 <option>-l</option>
9095 (or similar) options for linking with the libraries listed in &cv-link-LIBS;,
9096 nor
9097 <option>-L</option>
9098 (or similar) include search path options
9099 that scons generates automatically from &cv-link-LIBPATH;.
9100 See
9101 &cv-link-_LIBFLAGS;
9102 above,
9103 for the variable that expands to library-link options,
9104 and
9105 &cv-link-_LIBDIRFLAGS;
9106 above,
9107 for the variable that expands to library search path options.
9108 See also &cv-link-LINKFLAGS;  for linking static objects.
9109 </para>
9110 </listitem>
9111   </varlistentry>
9112   <varlistentry id="cv-SHOBJPREFIX">
9113     <term>
9114       <envar>SHOBJPREFIX</envar>
9115     </term>
9116     <listitem><para>
9117 The prefix used for shared object file names.
9118 </para>
9119 </listitem>
9120   </varlistentry>
9121   <varlistentry id="cv-SHOBJSUFFIX">
9122     <term>
9123       <envar>SHOBJSUFFIX</envar>
9124     </term>
9125     <listitem><para>
9126 The suffix used for shared object file names.
9127 </para>
9128 </listitem>
9129   </varlistentry>
9130   <varlistentry id="cv-SONAME">
9131     <term>
9132       <envar>SONAME</envar>
9133     </term>
9134     <listitem><para>
9135 Variable used to hard-code SONAME for versioned shared library/loadable module.
9136 <example_commands>
9137 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SONAME='libtest.so.2')
9138 </example_commands>
9139 The variable is used, for example, by &t-link-gnulink; linker tool.
9140 </para>
9141 </listitem>
9142   </varlistentry>
9143   <varlistentry id="cv-SOURCE">
9144     <term>
9145       <envar>SOURCE</envar>
9146     </term>
9147     <listitem><para>
9148 A reserved variable name
9149 that may not be set or used in a construction environment.
9150 (See the manpage section "Variable Substitution"
9151 for more information).
9152 </para>
9153 </listitem>
9154   </varlistentry>
9155   <varlistentry id="cv-SOURCE_URL">
9156     <term>
9157       <envar>SOURCE_URL</envar>
9158     </term>
9159     <listitem><para>
9160 The URL
9161 (web address)
9162 of the location from which the project was retrieved.
9163 This is used to fill in the
9164 <literal>Source:</literal>
9165 field in the controlling information for Ipkg and RPM packages.
9166 </para>
9167 <para>See the &b-link-Package; builder.</para>
9168 </listitem>
9169   </varlistentry>
9170   <varlistentry id="cv-SOURCES">
9171     <term>
9172       <envar>SOURCES</envar>
9173     </term>
9174     <listitem><para>
9175 A reserved variable name
9176 that may not be set or used in a construction environment.
9177 (See the manpage section "Variable Substitution"
9178 for more information).
9179 </para>
9180 </listitem>
9181   </varlistentry>
9182   <varlistentry id="cv-SOVERSION">
9183     <term>
9184       <envar>SOVERSION</envar>
9185     </term>
9186     <listitem><para>
9187 This will construct the <varname>SONAME</varname> using on the base library name
9188 (<parameter>test</parameter> in the example below) and use specified <varname>SOVERSION</varname>
9189 to create <varname>SONAME</varname>.
9190 <example_commands>
9191 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SOVERSION='2')
9192 </example_commands>
9193 The variable is used, for example, by &t-link-gnulink; linker tool.
9194 </para>
9195 <para>
9196 In the example above <varname>SONAME</varname> would be <filename>libtest.so.2</filename>
9197 which would be a symlink and point to <filename>libtest.so.0.1.2</filename>
9198 </para>
9199 </listitem>
9200   </varlistentry>
9201   <varlistentry id="cv-SPAWN">
9202     <term>
9203       <envar>SPAWN</envar>
9204     </term>
9205     <listitem><para>
9206 A command interpreter function that will be called to execute command line
9207 strings. The function must accept five arguments:
9208 </para>
9209
9210 <example_commands>
9211 def spawn(shell, escape, cmd, args, env):
9212 </example_commands>
9213
9214 <para>
9215 <varname>shell</varname>
9216 is a string naming the shell program to use,
9217 <varname>escape</varname>
9218 is a function that can be called to escape shell special characters in
9219 the command line,
9220 <varname>cmd</varname>
9221 is the path to the command to be executed,
9222 <varname>args</varname>
9223 holds the arguments to the command and
9224 <varname>env</varname>
9225 is a dictionary of environment variables
9226 defining the execution environment in which the command should be executed.
9227 </para>
9228 </listitem>
9229   </varlistentry>
9230   <varlistentry id="cv-STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME">
9231     <term>
9232       <envar>STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME</envar>
9233     </term>
9234     <listitem><para>
9235       When this variable is true, static objects and shared objects are assumed to be the same; that is, SCons does not check for linking static objects into a shared library.
9236     </para>
9237   </listitem>
9238   </varlistentry>
9239   <varlistentry id="cv-SUBST_DICT">
9240     <term>
9241       <envar>SUBST_DICT</envar>
9242     </term>
9243     <listitem><para>
9244 The dictionary used by the &b-link-Substfile; or &b-link-Textfile; builders
9245 for substitution values.
9246 It can be anything acceptable to the <function>dict()</function> constructor,
9247 so in addition to a dictionary,
9248 lists of tuples are also acceptable.
9249 </para>
9250 </listitem>
9251   </varlistentry>
9252   <varlistentry id="cv-SUBSTFILEPREFIX">
9253     <term>
9254       <envar>SUBSTFILEPREFIX</envar>
9255     </term>
9256     <listitem><para>
9257 The prefix used for &b-link-Substfile; file names,
9258 an empty string by default.
9259 </para>
9260 </listitem>
9261   </varlistentry>
9262   <varlistentry id="cv-SUBSTFILESUFFIX">
9263     <term>
9264       <envar>SUBSTFILESUFFIX</envar>
9265     </term>
9266     <listitem><para>
9267 The suffix used for &b-link-Substfile; file names,
9268 an empty string by default.
9269 </para>
9270 </listitem>
9271   </varlistentry>
9272   <varlistentry id="cv-SUMMARY">
9273     <term>
9274       <envar>SUMMARY</envar>
9275     </term>
9276     <listitem><para>
9277 A short summary of what the project is about.
9278 This is used to fill in the
9279 <literal>Summary:</literal>
9280 field in the controlling information for Ipkg and RPM packages,
9281 and as the
9282 <literal>Description:</literal>
9283 field in MSI packages.
9284 </para>
9285 <para>See the &b-link-Package; builder.</para>
9286 </listitem>
9287   </varlistentry>
9288   <varlistentry id="cv-SWIG">
9289     <term>
9290       <envar>SWIG</envar>
9291     </term>
9292     <listitem><para>
9293 The name of the &swig; compiler to use.
9294 </para>
9295 </listitem>
9296   </varlistentry>
9297   <varlistentry id="cv-SWIGCFILESUFFIX">
9298     <term>
9299       <envar>SWIGCFILESUFFIX</envar>
9300     </term>
9301     <listitem><para>
9302 The suffix that will be used for intermediate C
9303 source files generated by &swig;.
9304 The default value is <literal>'_wrap$CFILESUFFIX'</literal> -
9305 that is, the concatenation of the string
9306 <literal>_wrap</literal>
9307 and the current C suffix &cv-link-CFILESUFFIX;.
9308 By default, this value is used whenever the
9309 <option>-c++</option>
9310 option is
9311 <emphasis>not</emphasis>
9312 specified as part of the
9313 &cv-link-SWIGFLAGS;
9314 construction variable.
9315 </para>
9316 </listitem>
9317   </varlistentry>
9318   <varlistentry id="cv-SWIGCOM">
9319     <term>
9320       <envar>SWIGCOM</envar>
9321     </term>
9322     <listitem><para>
9323 The command line used to call &swig;.
9324 </para>
9325 </listitem>
9326   </varlistentry>
9327   <varlistentry id="cv-SWIGCOMSTR">
9328     <term>
9329       <envar>SWIGCOMSTR</envar>
9330     </term>
9331     <listitem><para>
9332 The string displayed when calling &swig;.
9333 If this is not set, then &cv-link-SWIGCOM; (the command line) is displayed.
9334 </para>
9335 </listitem>
9336   </varlistentry>
9337   <varlistentry id="cv-SWIGCXXFILESUFFIX">
9338     <term>
9339       <envar>SWIGCXXFILESUFFIX</envar>
9340     </term>
9341     <listitem><para>
9342 The suffix that will be used for intermediate C++
9343 source files generated by &swig;.
9344 The default value is <literal>'_wrap$CXXFILESUFFIX'</literal> -
9345 that is, the concatenation of the string
9346 <literal>_wrap</literal>
9347 and the current C++ suffix &cv-link-CXXFILESUFFIX;.
9348 By default, this value is used whenever the
9349 <option>-c++</option>
9350 option is specified as part of the
9351 &cv-link-SWIGFLAGS;
9352 construction variable.
9353 </para>
9354 </listitem>
9355   </varlistentry>
9356   <varlistentry id="cv-SWIGDIRECTORSUFFIX">
9357     <term>
9358       <envar>SWIGDIRECTORSUFFIX</envar>
9359     </term>
9360     <listitem><para>
9361 The suffix that will be used for intermediate C++ header
9362 files generated by &swig;.
9363 These are only generated for C++ code when the &swig; 'directors' feature is
9364 turned on.
9365 The default value is
9366 <filename>_wrap.h</filename>.
9367 </para>
9368 </listitem>
9369   </varlistentry>
9370   <varlistentry id="cv-SWIGFLAGS">
9371     <term>
9372       <envar>SWIGFLAGS</envar>
9373     </term>
9374     <listitem><para>
9375 General options passed to &swig;.
9376 This is where you should set the target language
9377 (<option>-python</option>,
9378 <option>-perl5</option>,
9379 <option>-tcl</option>, etc.)
9380 and whatever other options you want to specify to &swig;,
9381 such as the <option>-c++</option> to generate C++ code
9382 instead of C Code.
9383 </para>
9384 </listitem>
9385   </varlistentry>
9386   <varlistentry id="cv-_SWIGINCFLAGS">
9387     <term>
9388       <envar>_SWIGINCFLAGS</envar>
9389     </term>
9390     <listitem><para>
9391 An automatically-generated construction variable
9392 containing the &swig; command-line options
9393 for specifying directories to be searched for included files.
9394 The value of &cv-_SWIGINCFLAGS; is created
9395 by respectively prepending and appending
9396 &cv-SWIGINCPREFIX; and &cv-SWIGINCSUFFIX;
9397 to the beginning and end
9398 of each directory in &cv-SWIGPATH;.
9399 </para>
9400 </listitem>
9401   </varlistentry>
9402   <varlistentry id="cv-SWIGINCPREFIX">
9403     <term>
9404       <envar>SWIGINCPREFIX</envar>
9405     </term>
9406     <listitem><para>
9407 The prefix used to specify an include directory on the &swig; command line.
9408 This will be prepended to the beginning of each directory
9409 in the &cv-SWIGPATH; construction variable
9410 when the &cv-_SWIGINCFLAGS; variable is automatically generated.
9411 </para>
9412 </listitem>
9413   </varlistentry>
9414   <varlistentry id="cv-SWIGINCSUFFIX">
9415     <term>
9416       <envar>SWIGINCSUFFIX</envar>
9417     </term>
9418     <listitem><para>
9419 The suffix used to specify an include directory on the &swig; command line.
9420 This will be appended to the end of each directory
9421 in the &cv-SWIGPATH; construction variable
9422 when the &cv-_SWIGINCFLAGS; variable is automatically generated.
9423 </para>
9424 </listitem>
9425   </varlistentry>
9426   <varlistentry id="cv-SWIGOUTDIR">
9427     <term>
9428       <envar>SWIGOUTDIR</envar>
9429     </term>
9430     <listitem><para>
9431 Specifies the output directory in which &swig;
9432 should place generated language-specific files.
9433 This will be used by SCons to identify
9434 the files that will be generated by the &swig; call,
9435 and translated into the
9436 <literal>swig -outdir</literal> option on the command line.
9437 </para>
9438 </listitem>
9439   </varlistentry>
9440   <varlistentry id="cv-SWIGPATH">
9441     <term>
9442       <envar>SWIGPATH</envar>
9443     </term>
9444     <listitem><para>
9445 The list of directories that &swig;
9446 will search for included files.
9447 &SCons;' SWIG implicit dependency scanner will search these
9448 directories for include files. The default value is an empty list.
9449 </para>
9450
9451 <para>
9452 Don't explicitly put include directory
9453 arguments in &cv-link-SWIGFLAGS;
9454 the result will be non-portable
9455 and the directories will not be searched by the dependency scanner.
9456 Note: directory names in &cv-link-SWIGPATH;
9457 will be looked-up relative to the SConscript
9458 directory when they are used in a command.
9459 To force
9460 &scons;
9461 to look-up a directory relative to the root of the source tree use
9462 a top-relative path (<literal>#</literal>):
9463 </para>
9464
9465 <example_commands>
9466 env = Environment(SWIGPATH='#/include')
9467 </example_commands>
9468
9469 <para>
9470 The directory look-up can also be forced using the
9471 &Dir;()
9472 function:
9473 </para>
9474
9475 <example_commands>
9476 include = Dir('include')
9477 env = Environment(SWIGPATH=include)
9478 </example_commands>
9479
9480 <para>
9481 The directory list will be added to command lines
9482 through the automatically-generated
9483 &cv-_SWIGINCFLAGS;
9484 construction variable,
9485 which is constructed by
9486 respectively prepending and appending the values of the
9487 &cv-SWIGINCPREFIX; and &cv-SWIGINCSUFFIX;
9488 construction variables
9489 to the beginning and end
9490 of each directory in &cv-SWIGPATH;.
9491 Any command lines you define that need
9492 the SWIGPATH directory list should
9493 include &cv-_SWIGINCFLAGS;:
9494 </para>
9495
9496 <example_commands>
9497 env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SOURCES")
9498 </example_commands>
9499 </listitem>
9500   </varlistentry>
9501   <varlistentry id="cv-SWIGVERSION">
9502     <term>
9503       <envar>SWIGVERSION</envar>
9504     </term>
9505     <listitem><para>
9506 The detected version string of the &swig; tool.
9507 </para>
9508 </listitem>
9509   </varlistentry>
9510   <varlistentry id="cv-TAR">
9511     <term>
9512       <envar>TAR</envar>
9513     </term>
9514     <listitem><para>
9515 The tar archiver.
9516 </para>
9517 </listitem>
9518   </varlistentry>
9519   <varlistentry id="cv-TARCOM">
9520     <term>
9521       <envar>TARCOM</envar>
9522     </term>
9523     <listitem><para>
9524 The command line used to call the tar archiver.
9525 </para>
9526 </listitem>
9527   </varlistentry>
9528   <varlistentry id="cv-TARCOMSTR">
9529     <term>
9530       <envar>TARCOMSTR</envar>
9531     </term>
9532     <listitem><para>
9533 The string displayed when archiving files
9534 using the tar archiver.
9535 If this is not set, then &cv-link-TARCOM; (the command line) is displayed.
9536 </para>
9537
9538 <example_commands>
9539 env = Environment(TARCOMSTR = "Archiving $TARGET")
9540 </example_commands>
9541 </listitem>
9542   </varlistentry>
9543   <varlistentry id="cv-TARFLAGS">
9544     <term>
9545       <envar>TARFLAGS</envar>
9546     </term>
9547     <listitem><para>
9548 General options passed to the tar archiver.
9549 </para>
9550 </listitem>
9551   </varlistentry>
9552   <varlistentry id="cv-TARGET">
9553     <term>
9554       <envar>TARGET</envar>
9555     </term>
9556     <listitem><para>
9557 A reserved variable name
9558 that may not be set or used in a construction environment.
9559 (See the manpage section "Variable Substitution"
9560 for more information).
9561 </para>
9562 </listitem>
9563   </varlistentry>
9564   <varlistentry id="cv-TARGET_ARCH">
9565     <term>
9566       <envar>TARGET_ARCH</envar>
9567     </term>
9568     <listitem><para>
9569       The name of the hardware architecture that objects
9570       created using this &consenv; should target.
9571       Can be set when creating a &consenv; by passing as a keyword
9572       argument in the &f-link-Environment; call.
9573     </para>
9574     <para>
9575       On the <literal>win32</literal> platform,
9576       if the &MSVC; compiler is available,
9577       &t-link-msvc; tool setup is done using
9578       &cv-link-HOST_ARCH; and &cv-TARGET_ARCH;.
9579       If a value is not specified,
9580       will be set to the same value as &cv-link-HOST_ARCH;.
9581       Changing the value after the environment is initialized
9582       will not cause the tool to be reinitialized.
9583       Compiled objects will be in the target architecture if
9584       the compilation system supports generating for that target.
9585       The latest compiler which can fulfill the requirement will
9586       be selected, unless a different version is directed by the
9587       value of the &cv-link-MSVC_VERSION; &consvar;.
9588     </para>
9589     <para>
9590       On the win32/msvc combination, valid target arch values are
9591       <literal>x86</literal>,
9592       <literal>arm</literal>,
9593       <literal>i386</literal>
9594       for 32-bit targets and
9595       <literal>amd64</literal>,
9596       <literal>arm64</literal>,
9597       <literal>x86_64</literal>
9598       and <literal>ia64</literal> (Itanium)
9599       for 64-bit targets.
9600       For example, if you want to compile 64-bit binaries, you would set
9601       <literal>TARGET_ARCH='x86_64'</literal> when creating the &consenv;.
9602       Note that not all target architectures are
9603       supported for all Visual Studio / MSVC versions.
9604       Check the relevant Microsoft documentation.
9605     </para>
9606     <para>
9607       &cv-TARGET_ARCH; is not currently used by other compilation tools,
9608       but the option is reserved to do so in future
9609     </para>
9610   </listitem>
9611   </varlistentry>
9612   <varlistentry id="cv-TARGET_OS">
9613     <term>
9614       <envar>TARGET_OS</envar>
9615     </term>
9616     <listitem><para>
9617       The name of the operating system that objects
9618       created using this &consenv; should target.
9619       Can be set when creating a &consenv; by passing as a keyword
9620       argument in the &f-link-Environment; call;.
9621     </para>
9622     <para>
9623       &cv-TARGET_OS; is not currently used by &SCons;
9624       but the option is reserved to do so in future
9625     </para>
9626   </listitem>
9627   </varlistentry>
9628   <varlistentry id="cv-TARGETS">
9629     <term>
9630       <envar>TARGETS</envar>
9631     </term>
9632     <listitem><para>
9633 A reserved variable name
9634 that may not be set or used in a construction environment.
9635 (See the manpage section "Variable Substitution"
9636 for more information).
9637 </para>
9638 </listitem>
9639   </varlistentry>
9640   <varlistentry id="cv-TARSUFFIX">
9641     <term>
9642       <envar>TARSUFFIX</envar>
9643     </term>
9644     <listitem><para>
9645 The suffix used for tar file names.
9646 </para>
9647 </listitem>
9648   </varlistentry>
9649   <varlistentry id="cv-TEMPFILE">
9650     <term>
9651       <envar>TEMPFILE</envar>
9652     </term>
9653     <listitem><para>
9654 Holds a callable object which will be invoked to transform long
9655 command lines (string or list) into an alternate form.
9656 Length limits on various operating systems
9657 may cause long command lines to fail when calling out to
9658 a shell to run the command.
9659 Most often affects linking, when there are many object files and/or
9660 libraries to be linked, but may also affect other
9661 compilation steps which have many arguments.
9662 &cv-TEMPFILE; is not called directly,
9663 but rather is typically embedded in another
9664 &consvar;, to be expanded when used. Example:
9665 </para>
9666
9667 <example_commands>
9668 env["TEMPFILE"] = TempFileMunge
9669 env["LINKCOM"] = "${TEMPFILE('$LINK $TARGET $SOURCES', '$LINKCOMSTR')}"
9670 </example_commands>
9671
9672 <para>
9673 The SCons default value for &cv-TEMPFILE;,
9674 <classname>TempFileMunge</classname>,
9675 performs command substitution on the passed command line,
9676 calculates whether modification is needed,
9677 then puts all but the first word (assumed to be the command name)
9678 of the resulting list into a temporary file
9679 (sometimes called a response file or command file),
9680 and returns a new command line consisting of the
9681 the command name and an appropriately formatted reference
9682 to the temporary file.
9683 </para>
9684
9685 <para>
9686 A replacement for the default tempfile object would need
9687 to do fundamentally the same thing, including taking into account
9688 the values of
9689 &cv-link-MAXLINELENGTH;,
9690 &cv-link-TEMPFILEPREFIX;,
9691 &cv-link-TEMPFILESUFFIX;,
9692 &cv-link-TEMPFILEARGJOIN;,
9693 &cv-link-TEMPFILEDIR;
9694 and
9695 &cv-link-TEMPFILEARGESCFUNC;.
9696 If a particular use case requires a different transformation
9697 than the default, it is recommended to copy the mechanism and
9698 define a new &consvar; and rewrite the relevant <literal>*COM</literal>
9699 variable(s) to use it, to avoid possibly disrupting existing uses
9700 of &cv-TEMPFILE;.
9701 </para>
9702 </listitem>
9703   </varlistentry>
9704   <varlistentry id="cv-TEMPFILEARGESCFUNC">
9705     <term>
9706       <envar>TEMPFILEARGESCFUNC</envar>
9707     </term>
9708     <listitem><para>
9709 The default argument escape function is
9710 <function>SCons.Subst.quote_spaces</function>.
9711 If you need to apply extra operations on a command argument
9712 (to fix Windows slashes, normalize paths, etc.)
9713 before writing to the temporary file,
9714 you can set the &cv-TEMPFILEARGESCFUNC; variable to a custom function.
9715 Such a function takes a single string argument and returns
9716 a new string with any modifications applied.
9717 Example:
9718 </para>
9719
9720 <example_commands>
9721 import sys
9722 import re
9723 from SCons.Subst import quote_spaces
9724
9725 WINPATHSEP_RE = re.compile(r"\\([^\"'\\]|$)")
9726
9727 def tempfile_arg_esc_func(arg):
9728     arg = quote_spaces(arg)
9729     if sys.platform != "win32":
9730         return arg
9731     # GCC requires double Windows slashes, let's use UNIX separator
9732     return WINPATHSEP_RE.sub(r"/\1", arg)
9733
9734 env["TEMPFILEARGESCFUNC"] = tempfile_arg_esc_func
9735 </example_commands>
9736 </listitem>
9737   </varlistentry>
9738   <varlistentry id="cv-TEMPFILEARGJOIN">
9739     <term>
9740       <envar>TEMPFILEARGJOIN</envar>
9741     </term>
9742     <listitem><para>
9743 The string to use to join the arguments passed to
9744 &cv-link-TEMPFILE; when the command line exceeds the limit set by
9745 &cv-link-MAXLINELENGTH;.
9746 The default value is a space.
9747 However for MSVC, MSLINK the default is a line separator
9748 as defined by <systemitem>os.linesep</systemitem>.
9749 Note this value is used literally and not expanded by the subst logic.
9750 </para>
9751 </listitem>
9752   </varlistentry>
9753   <varlistentry id="cv-TEMPFILEDIR">
9754     <term>
9755       <envar>TEMPFILEDIR</envar>
9756     </term>
9757     <listitem><para>
9758 The directory to create the long-lines temporary file in.
9759 If unset, some suitable default should be chosen.
9760 The default tempfile object lets the &Python;
9761 <systemitem>tempfile</systemitem> module choose.
9762 </para>
9763 </listitem>
9764   </varlistentry>
9765   <varlistentry id="cv-TEMPFILEPREFIX">
9766     <term>
9767       <envar>TEMPFILEPREFIX</envar>
9768     </term>
9769     <listitem><para>
9770 The prefix for the name of the temporary file used
9771 to store command lines exceeding &cv-link-MAXLINELENGTH;.
9772 The prefix must include the compiler syntax to actually
9773 include and process the file.
9774 The default prefix is <literal>'@'</literal>, which works for the &MSVC;
9775 and GNU toolchains on Windows.
9776 Set this appropriately for other toolchains,
9777 for example <literal>'-@'</literal> for the diab compiler
9778 or <literal>'-via'</literal> for ARM toolchain.
9779 </para>
9780 </listitem>
9781   </varlistentry>
9782   <varlistentry id="cv-TEMPFILESUFFIX">
9783     <term>
9784       <envar>TEMPFILESUFFIX</envar>
9785     </term>
9786     <listitem><para>
9787 The suffix for the name of the temporary file used
9788 to store command lines exceeding &cv-link-MAXLINELENGTH;.
9789 The suffix should include the dot ('.') if one is needed as
9790 it will not be added automatically.
9791 The default is <filename>.lnk</filename>.
9792 </para>
9793 </listitem>
9794   </varlistentry>
9795   <varlistentry id="cv-TEX">
9796     <term>
9797       <envar>TEX</envar>
9798     </term>
9799     <listitem><para>
9800 The TeX formatter and typesetter.
9801 </para>
9802 </listitem>
9803   </varlistentry>
9804   <varlistentry id="cv-TEXCOM">
9805     <term>
9806       <envar>TEXCOM</envar>
9807     </term>
9808     <listitem><para>
9809 The command line used to call the TeX formatter and typesetter.
9810 </para>
9811 </listitem>
9812   </varlistentry>
9813   <varlistentry id="cv-TEXCOMSTR">
9814     <term>
9815       <envar>TEXCOMSTR</envar>
9816     </term>
9817     <listitem><para>
9818 The string displayed when calling
9819 the TeX formatter and typesetter.
9820 If this is not set, then &cv-link-TEXCOM; (the command line) is displayed.
9821 </para>
9822
9823 <example_commands>
9824 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
9825 </example_commands>
9826 </listitem>
9827   </varlistentry>
9828   <varlistentry id="cv-TEXFLAGS">
9829     <term>
9830       <envar>TEXFLAGS</envar>
9831     </term>
9832     <listitem><para>
9833 General options passed to the TeX formatter and typesetter.
9834 </para>
9835 </listitem>
9836   </varlistentry>
9837   <varlistentry id="cv-TEXINPUTS">
9838     <term>
9839       <envar>TEXINPUTS</envar>
9840     </term>
9841     <listitem><para>
9842 List of directories that the LaTeX program will search
9843 for include directories.
9844 The LaTeX implicit dependency scanner will search these
9845 directories for \include and \import files.
9846 </para>
9847 </listitem>
9848   </varlistentry>
9849   <varlistentry id="cv-TEXTFILEPREFIX">
9850     <term>
9851       <envar>TEXTFILEPREFIX</envar>
9852     </term>
9853     <listitem><para>
9854 The prefix used for &b-link-Textfile; file names,
9855 an empty string by default.
9856 </para>
9857 </listitem>
9858   </varlistentry>
9859   <varlistentry id="cv-TEXTFILESUFFIX">
9860     <term>
9861       <envar>TEXTFILESUFFIX</envar>
9862     </term>
9863     <listitem><para>
9864 The suffix used for &b-link-Textfile; file names;
9865 <filename>.txt</filename> by default.
9866 </para>
9867 </listitem>
9868   </varlistentry>
9869   <varlistentry id="cv-TOOLS">
9870     <term>
9871       <envar>TOOLS</envar>
9872     </term>
9873     <listitem><para>
9874 A list of the names of the Tool specification modules
9875 that were actually initialized in the current &consenv;.
9876 This may be useful as a diagnostic aid
9877 to see if a tool did (or did not) run.
9878 The value is informative and is not guaranteed to be complete.
9879 </para>
9880 </listitem>
9881   </varlistentry>
9882   <varlistentry id="cv-UNCHANGED_SOURCES">
9883     <term>
9884       <envar>UNCHANGED_SOURCES</envar>
9885     </term>
9886     <listitem><para>
9887 A reserved variable name
9888 that may not be set or used in a construction environment.
9889 (See the manpage section "Variable Substitution"
9890 for more information).
9891 </para>
9892 </listitem>
9893   </varlistentry>
9894   <varlistentry id="cv-UNCHANGED_TARGETS">
9895     <term>
9896       <envar>UNCHANGED_TARGETS</envar>
9897     </term>
9898     <listitem><para>
9899 A reserved variable name
9900 that may not be set or used in a construction environment.
9901 (See the manpage section "Variable Substitution"
9902 for more information).
9903 </para>
9904 </listitem>
9905   </varlistentry>
9906   <varlistentry id="cv-VENDOR">
9907     <term>
9908       <envar>VENDOR</envar>
9909     </term>
9910     <listitem><para>
9911 The person or organization who supply the packaged software.
9912 This is used to fill in the
9913 <literal>Vendor:</literal>
9914 field in the controlling information for RPM packages,
9915 and the
9916 <literal>Manufacturer:</literal>
9917 field in the controlling information for MSI packages.
9918 </para>
9919 <para>See the &b-link-Package; builder.</para>
9920 </listitem>
9921   </varlistentry>
9922   <varlistentry id="cv-VERSION">
9923     <term>
9924       <envar>VERSION</envar>
9925     </term>
9926     <listitem><para>
9927 The version of the project, specified as a string.
9928 </para>
9929 <para>See the &b-link-Package; builder.</para>
9930 </listitem>
9931   </varlistentry>
9932   <varlistentry id="cv-VSWHERE">
9933     <term>
9934       <envar>VSWHERE</envar>
9935     </term>
9936     <listitem><para>
9937 Specify the location of <command>vswhere.exe</command>.
9938 </para>
9939
9940 <para>
9941     The <command>vswhere.exe</command> executable is distributed with
9942     Microsoft Visual Studio and Build Tools since the 2017 edition,
9943     but is also available as a standalone installation.
9944     It allows queries to obtain detailed information about
9945     installations of 2017 and later editions.
9946     &SCons; makes use of this information to determine
9947     the state of compiler support for those editions.
9948 </para>
9949 <para>
9950     Setting the &cv-VSWHERE; variable to the path to a specific
9951     <command>vswhere.exe</command> binary
9952     causes &SCons; to use that binary.
9953     If not set, &SCons; will search for one,
9954     looking in the following locations in order,
9955     using the first found
9956     (&cv-VSWHERE; is updated with the location):
9957 </para>
9958
9959 <simplelist type="vert">
9960 <member><literal>%ProgramFiles(x86)%\Microsoft Visual Studio\Installer</literal></member>
9961 <member><literal>%ProgramFiles%\Microsoft Visual Studio\Installer</literal></member>
9962 <member><literal>%ChocolateyInstall%\bin</literal></member>
9963 <member><literal>%LOCALAPPDATA%\Microsoft\WinGet\Links</literal></member>
9964 <member><literal>%USERPROFILE%\scoop\shims</literal></member>
9965 <member><literal>%SCOOP%\shims</literal></member>
9966 </simplelist>
9967
9968
9969 <note>
9970   <para>
9971     In order to take effect, &cv-VSWHERE; must be set before
9972     the initial &MSVC; compiler discovery takes place.
9973     Discovery happens, at the latest, during the first call to the
9974     &f-link-Environment; function, unless a <parameter>tools</parameter>
9975     list is specified which excludes the entire &MSVC; toolchain -
9976     that is, omits <literal>"defaults"</literal>
9977     and any specific tool module that refers to parts of the toolchain
9978     (&t-link-msvc;, &t-link-mslink;, &t-link-masm;, &t-link-midl;
9979     and &t-link-msvs;). In this case, detection is deferred until
9980     any one of those tool modules is invoked manually.
9981     The following two examples illustrate this:
9982   </para>
9983
9984   <programlisting>
9985 # VSWHERE set as Environment is created
9986 env = Environment(VSWHERE='c:/my/path/to/vswhere')
9987
9988 # Initialization deferred with empty tools, triggered manually
9989 env = Environment(tools=[])
9990 env['VSWHERE'] = r'c:/my/vswhere/install/location/vswhere.exe'
9991 env.Tool('msvc')
9992 env.Tool('mslink')
9993 env.Tool('msvs')
9994   </programlisting>
9995 </note>
9996
9997 </listitem>
9998   </varlistentry>
9999   <varlistentry id="cv-WINDOWS_EMBED_MANIFEST">
10000     <term>
10001       <envar>WINDOWS_EMBED_MANIFEST</envar>
10002     </term>
10003     <listitem><para>
10004 Set to <constant>True</constant> to embed the
10005 compiler-generated manifest
10006 (normally <literal>${TARGET}.manifest</literal>)
10007 into all Windows executables and DLLs built with this environment,
10008 as a resource during their link step.
10009 This is done using &cv-link-MT; and &cv-link-MTEXECOM; and &cv-link-MTSHLIBCOM;.
10010 See also &cv-link-WINDOWS_INSERT_MANIFEST;.
10011 </para>
10012 </listitem>
10013   </varlistentry>
10014   <varlistentry id="cv-WINDOWS_INSERT_DEF">
10015     <term>
10016       <envar>WINDOWS_INSERT_DEF</envar>
10017     </term>
10018     <listitem><para>
10019 If set to true,
10020 a library build of a Windows shared library
10021 (<filename>.dll</filename> file)
10022 will include a reference to the corresponding
10023 module-definition file at the same time,
10024 if a module-definition file
10025 is not already listed as a build target.
10026 The name of the module-definition file will
10027 be constructed from the base name of the library
10028 and the &consvars;
10029 &cv-link-WINDOWSDEFSUFFIX; and
10030 &cv-link-WINDOWSDEFPREFIX;.
10031 The default is to not add a module-definition file.
10032 The module-definition file is not created by this directive,
10033 and must be supplied by the developer.
10034 </para>
10035 </listitem>
10036   </varlistentry>
10037   <varlistentry id="cv-WINDOWS_INSERT_MANIFEST">
10038     <term>
10039       <envar>WINDOWS_INSERT_MANIFEST</envar>
10040     </term>
10041     <listitem><para>
10042 If set to true,
10043 &scons;
10044 will add the manifest file
10045 generated by &MSVC; 8.0 and later
10046 to the target list so &SCons; will be aware they
10047 were generated.
10048 In the case of an executable, the manifest file name
10049 is constructed using
10050 &cv-link-WINDOWSPROGMANIFESTSUFFIX; and
10051 &cv-link-WINDOWSPROGMANIFESTPREFIX;.
10052 In the case of a shared library, the manifest file name
10053 is constructed using
10054 &cv-link-WINDOWSSHLIBMANIFESTSUFFIX; and
10055 &cv-link-WINDOWSSHLIBMANIFESTPREFIX;.
10056 See also &cv-link-WINDOWS_EMBED_MANIFEST;.
10057 </para>
10058 </listitem>
10059   </varlistentry>
10060   <varlistentry id="cv-WINDOWSDEFPREFIX">
10061     <term>
10062       <envar>WINDOWSDEFPREFIX</envar>
10063     </term>
10064     <listitem><para>
10065 The prefix used for a Windows linker module-definition file name.
10066 Defaults to empty.
10067 </para>
10068 </listitem>
10069   </varlistentry>
10070   <varlistentry id="cv-WINDOWSDEFSUFFIX">
10071     <term>
10072       <envar>WINDOWSDEFSUFFIX</envar>
10073     </term>
10074     <listitem><para>
10075 The suffix used for a Windows linker module-definition file name.
10076 Defaults to <filename>.def</filename>.
10077 </para>
10078 </listitem>
10079   </varlistentry>
10080   <varlistentry id="cv-WINDOWSEXPPREFIX">
10081     <term>
10082       <envar>WINDOWSEXPPREFIX</envar>
10083     </term>
10084     <listitem><para>
10085 The prefix used for Windows linker exports file names.
10086 Defaults to empty.
10087 </para>
10088 </listitem>
10089   </varlistentry>
10090   <varlistentry id="cv-WINDOWSEXPSUFFIX">
10091     <term>
10092       <envar>WINDOWSEXPSUFFIX</envar>
10093     </term>
10094     <listitem><para>
10095 The suffix used for Windows linker exports file names.
10096 Defaults to <filename>.exp</filename>.
10097 </para>
10098 </listitem>
10099   </varlistentry>
10100   <varlistentry id="cv-WINDOWSPROGMANIFESTPREFIX">
10101     <term>
10102       <envar>WINDOWSPROGMANIFESTPREFIX</envar>
10103     </term>
10104     <listitem><para>
10105 The prefix used for executable program manifest files
10106 generated by &MSVC;.
10107 Defaults to empty.
10108 </para>
10109 </listitem>
10110   </varlistentry>
10111   <varlistentry id="cv-WINDOWSPROGMANIFESTSUFFIX">
10112     <term>
10113       <envar>WINDOWSPROGMANIFESTSUFFIX</envar>
10114     </term>
10115     <listitem><para>
10116 The suffix used for executable program manifest files
10117 generated by &MSVC;.
10118 Defaults to <filename>.manifest</filename>.
10119 </para>
10120 </listitem>
10121   </varlistentry>
10122   <varlistentry id="cv-WINDOWSSHLIBMANIFESTPREFIX">
10123     <term>
10124       <envar>WINDOWSSHLIBMANIFESTPREFIX</envar>
10125     </term>
10126     <listitem><para>
10127 The prefix used for shared library manifest files
10128 generated by &MSVC;.
10129 Defaults to empty.
10130 </para>
10131 </listitem>
10132   </varlistentry>
10133   <varlistentry id="cv-WINDOWSSHLIBMANIFESTSUFFIX">
10134     <term>
10135       <envar>WINDOWSSHLIBMANIFESTSUFFIX</envar>
10136     </term>
10137     <listitem><para>
10138 The suffix used for shared library manifest files
10139 generated by &MSVC;.
10140 Defaults to <filename>.manifest</filename>.
10141 </para>
10142 </listitem>
10143   </varlistentry>
10144   <varlistentry id="cv-X_IPK_DEPENDS">
10145     <term>
10146       <envar>X_IPK_DEPENDS</envar>
10147     </term>
10148     <listitem><para>
10149 This is used to fill in the
10150 <literal>Depends:</literal>
10151 field in the controlling information for Ipkg packages.
10152 </para>
10153 <para>See the &b-link-Package; builder.</para>
10154 </listitem>
10155   </varlistentry>
10156   <varlistentry id="cv-X_IPK_DESCRIPTION">
10157     <term>
10158       <envar>X_IPK_DESCRIPTION</envar>
10159     </term>
10160     <listitem><para>
10161 This is used to fill in the
10162 <literal>Description:</literal>
10163 field in the controlling information for Ipkg packages.
10164 The default value is
10165 <quote>&cv-SUMMARY;\n&cv-DESCRIPTION;</quote>
10166 </para>
10167 </listitem>
10168   </varlistentry>
10169   <varlistentry id="cv-X_IPK_MAINTAINER">
10170     <term>
10171       <envar>X_IPK_MAINTAINER</envar>
10172     </term>
10173     <listitem><para>
10174 This is used to fill in the
10175 <literal>Maintainer:</literal>
10176 field in the controlling information for Ipkg packages.
10177 </para>
10178 </listitem>
10179   </varlistentry>
10180   <varlistentry id="cv-X_IPK_PRIORITY">
10181     <term>
10182       <envar>X_IPK_PRIORITY</envar>
10183     </term>
10184     <listitem><para>
10185 This is used to fill in the
10186 <literal>Priority:</literal>
10187 field in the controlling information for Ipkg packages.
10188 </para>
10189 </listitem>
10190   </varlistentry>
10191   <varlistentry id="cv-X_IPK_SECTION">
10192     <term>
10193       <envar>X_IPK_SECTION</envar>
10194     </term>
10195     <listitem><para>
10196 This is used to fill in the
10197 <literal>Section:</literal>
10198 field in the controlling information for Ipkg packages.
10199 </para>
10200 </listitem>
10201   </varlistentry>
10202   <varlistentry id="cv-X_MSI_LANGUAGE">
10203     <term>
10204       <envar>X_MSI_LANGUAGE</envar>
10205     </term>
10206     <listitem><para>
10207 This is used to fill in the
10208 <literal>Language:</literal>
10209 attribute in the controlling information for MSI packages.
10210 </para>
10211 <para>See the &b-link-Package; builder.</para>
10212 </listitem>
10213   </varlistentry>
10214   <varlistentry id="cv-X_MSI_LICENSE_TEXT">
10215     <term>
10216       <envar>X_MSI_LICENSE_TEXT</envar>
10217     </term>
10218     <listitem><para>
10219 The text of the software license in RTF format.
10220 Carriage return characters will be
10221 replaced with the RTF equivalent \\par.
10222 </para>
10223 <para>See the &b-link-Package; builder.</para>
10224 </listitem>
10225   </varlistentry>
10226   <varlistentry id="cv-X_MSI_UPGRADE_CODE">
10227     <term>
10228       <envar>X_MSI_UPGRADE_CODE</envar>
10229     </term>
10230     <listitem><para>
10231 TODO
10232 </para>
10233 </listitem>
10234   </varlistentry>
10235   <varlistentry id="cv-X_RPM_AUTOREQPROV">
10236     <term>
10237       <envar>X_RPM_AUTOREQPROV</envar>
10238     </term>
10239     <listitem><para>
10240 This is used to fill in the
10241 <literal>AutoReqProv:</literal>
10242 field in the RPM
10243 <filename>.spec</filename> file.
10244 </para>
10245 <para>See the &b-link-Package; builder.</para>
10246 </listitem>
10247   </varlistentry>
10248   <varlistentry id="cv-X_RPM_BUILD">
10249     <term>
10250       <envar>X_RPM_BUILD</envar>
10251     </term>
10252     <listitem><para>
10253 internal, but overridable
10254 </para>
10255 </listitem>
10256   </varlistentry>
10257   <varlistentry id="cv-X_RPM_BUILDREQUIRES">
10258     <term>
10259       <envar>X_RPM_BUILDREQUIRES</envar>
10260     </term>
10261     <listitem><para>
10262 This is used to fill in the
10263 <literal>BuildRequires:</literal>
10264 field in the RPM
10265 <filename>.spec</filename> file.
10266 Note this should only be used on a host managed by rpm as the dependencies will not be resolvable at build time otherwise.
10267 </para>
10268 </listitem>
10269   </varlistentry>
10270   <varlistentry id="cv-X_RPM_BUILDROOT">
10271     <term>
10272       <envar>X_RPM_BUILDROOT</envar>
10273     </term>
10274     <listitem><para>
10275 internal, but overridable
10276 </para>
10277 </listitem>
10278   </varlistentry>
10279   <varlistentry id="cv-X_RPM_CLEAN">
10280     <term>
10281       <envar>X_RPM_CLEAN</envar>
10282     </term>
10283     <listitem><para>
10284 internal, but overridable
10285 </para>
10286 </listitem>
10287   </varlistentry>
10288   <varlistentry id="cv-X_RPM_CONFLICTS">
10289     <term>
10290       <envar>X_RPM_CONFLICTS</envar>
10291     </term>
10292     <listitem><para>
10293 This is used to fill in the
10294 <literal>Conflicts:</literal>
10295 field in the RPM
10296 <filename>.spec</filename> file.
10297 </para>
10298 </listitem>
10299   </varlistentry>
10300   <varlistentry id="cv-X_RPM_DEFATTR">
10301     <term>
10302       <envar>X_RPM_DEFATTR</envar>
10303     </term>
10304     <listitem><para>
10305 This value is used as the default attributes
10306 for the files in the RPM package.
10307 The default value is
10308 <quote>(-,root,root)</quote>.
10309 </para>
10310 </listitem>
10311   </varlistentry>
10312   <varlistentry id="cv-X_RPM_DISTRIBUTION">
10313     <term>
10314       <envar>X_RPM_DISTRIBUTION</envar>
10315     </term>
10316     <listitem><para>
10317 This is used to fill in the
10318 <literal>Distribution:</literal>
10319 field in the RPM
10320 <filename>.spec</filename> file.
10321 </para>
10322 </listitem>
10323   </varlistentry>
10324   <varlistentry id="cv-X_RPM_EPOCH">
10325     <term>
10326       <envar>X_RPM_EPOCH</envar>
10327     </term>
10328     <listitem><para>
10329 This is used to fill in the
10330 <literal>Epoch:</literal>
10331 field in the RPM
10332 <filename>.spec</filename> file.
10333 </para>
10334 </listitem>
10335   </varlistentry>
10336   <varlistentry id="cv-X_RPM_EXCLUDEARCH">
10337     <term>
10338       <envar>X_RPM_EXCLUDEARCH</envar>
10339     </term>
10340     <listitem><para>
10341 This is used to fill in the
10342 <literal>ExcludeArch:</literal>
10343 field in the RPM
10344 <filename>.spec</filename> file.
10345 </para>
10346 </listitem>
10347   </varlistentry>
10348   <varlistentry id="cv-X_RPM_EXLUSIVEARCH">
10349     <term>
10350       <envar>X_RPM_EXLUSIVEARCH</envar>
10351     </term>
10352     <listitem><para>
10353 This is used to fill in the
10354 <literal>ExclusiveArch:</literal>
10355 field in the RPM
10356 <filename>.spec</filename> file.
10357 </para>
10358 </listitem>
10359   </varlistentry>
10360   <varlistentry id="cv-X_RPM_EXTRADEFS">
10361     <term>
10362       <envar>X_RPM_EXTRADEFS</envar>
10363     </term>
10364     <listitem><para>
10365 A list used to supply extra defintions or flags
10366 to be added to the RPM <filename>.spec</filename> file.
10367 Each item is added as-is with a carriage return appended.
10368 This is useful if some specific RPM feature not otherwise
10369 anticipated by SCons needs to be turned on or off.
10370 Note if this variable is omitted, SCons will by
10371 default supply the value
10372 <literal>'%global debug_package %{nil}'</literal>
10373 to disable debug package generation.
10374 To enable debug package generation, include this
10375 variable set either to None, or to a custom
10376 list that does not include the default line.
10377 </para>
10378 <para>
10379 <emphasis>New in version  3.1.</emphasis>
10380 </para>
10381
10382 <example_commands>
10383 env.Package(
10384     NAME="foo",
10385     ...
10386     X_RPM_EXTRADEFS=[
10387         "%define _unpackaged_files_terminate_build 0"
10388         "%define _missing_doc_files_terminate_build 0"
10389     ],
10390     ...
10391 )
10392 </example_commands>
10393
10394 </listitem>
10395   </varlistentry>
10396   <varlistentry id="cv-X_RPM_GROUP">
10397     <term>
10398       <envar>X_RPM_GROUP</envar>
10399     </term>
10400     <listitem><para>
10401 This is used to fill in the
10402 <literal>Group:</literal>
10403 field in the RPM
10404 <filename>.spec</filename> file.
10405 </para>
10406 </listitem>
10407   </varlistentry>
10408   <varlistentry id="cv-X_RPM_GROUP_lang">
10409     <term>
10410       <envar>X_RPM_GROUP_lang</envar>
10411     </term>
10412     <listitem><para>
10413 This is used to fill in the
10414 <literal>Group(lang):</literal>
10415 field in the RPM
10416 <filename>.spec</filename> file.
10417 Note that
10418 <varname>lang</varname>
10419 is not literal
10420 and should be replaced by
10421 the appropriate language code.
10422 </para>
10423 </listitem>
10424   </varlistentry>
10425   <varlistentry id="cv-X_RPM_ICON">
10426     <term>
10427       <envar>X_RPM_ICON</envar>
10428     </term>
10429     <listitem><para>
10430 This is used to fill in the
10431 <literal>Icon:</literal>
10432 field in the RPM
10433 <filename>.spec</filename> file.
10434 </para>
10435 </listitem>
10436   </varlistentry>
10437   <varlistentry id="cv-X_RPM_INSTALL">
10438     <term>
10439       <envar>X_RPM_INSTALL</envar>
10440     </term>
10441     <listitem><para>
10442 internal, but overridable
10443 </para>
10444 </listitem>
10445   </varlistentry>
10446   <varlistentry id="cv-X_RPM_PACKAGER">
10447     <term>
10448       <envar>X_RPM_PACKAGER</envar>
10449     </term>
10450     <listitem><para>
10451 This is used to fill in the
10452 <literal>Packager:</literal>
10453 field in the RPM
10454 <filename>.spec</filename> file.
10455 </para>
10456 </listitem>
10457   </varlistentry>
10458   <varlistentry id="cv-X_RPM_POSTINSTALL">
10459     <term>
10460       <envar>X_RPM_POSTINSTALL</envar>
10461     </term>
10462     <listitem><para>
10463 This is used to fill in the
10464 <literal>%post:</literal>
10465 section in the RPM
10466 <filename>.spec</filename> file.
10467 </para>
10468 </listitem>
10469   </varlistentry>
10470   <varlistentry id="cv-X_RPM_POSTUNINSTALL">
10471     <term>
10472       <envar>X_RPM_POSTUNINSTALL</envar>
10473     </term>
10474     <listitem><para>
10475 This is used to fill in the
10476 <literal>%postun:</literal>
10477 section in the RPM
10478 <filename>.spec</filename> file.
10479 </para>
10480 </listitem>
10481   </varlistentry>
10482   <varlistentry id="cv-X_RPM_PREFIX">
10483     <term>
10484       <envar>X_RPM_PREFIX</envar>
10485     </term>
10486     <listitem><para>
10487 This is used to fill in the
10488 <literal>Prefix:</literal>
10489 field in the RPM
10490 <filename>.spec</filename> file.
10491 </para>
10492 </listitem>
10493   </varlistentry>
10494   <varlistentry id="cv-X_RPM_PREINSTALL">
10495     <term>
10496       <envar>X_RPM_PREINSTALL</envar>
10497     </term>
10498     <listitem><para>
10499 This is used to fill in the
10500 <literal>%pre:</literal>
10501 section in the RPM
10502 <filename>.spec</filename> file.
10503 </para>
10504 </listitem>
10505   </varlistentry>
10506   <varlistentry id="cv-X_RPM_PREP">
10507     <term>
10508       <envar>X_RPM_PREP</envar>
10509     </term>
10510     <listitem><para>
10511 internal, but overridable
10512 </para>
10513 </listitem>
10514   </varlistentry>
10515   <varlistentry id="cv-X_RPM_PREUNINSTALL">
10516     <term>
10517       <envar>X_RPM_PREUNINSTALL</envar>
10518     </term>
10519     <listitem><para>
10520 This is used to fill in the
10521 <literal>%preun:</literal>
10522 section in the RPM
10523 <filename>.spec</filename> file.
10524 </para>
10525 </listitem>
10526   </varlistentry>
10527   <varlistentry id="cv-X_RPM_PROVIDES">
10528     <term>
10529       <envar>X_RPM_PROVIDES</envar>
10530     </term>
10531     <listitem><para>
10532 This is used to fill in the
10533 <literal>Provides:</literal>
10534 field in the RPM
10535 <filename>.spec</filename> file.
10536 </para>
10537 </listitem>
10538   </varlistentry>
10539   <varlistentry id="cv-X_RPM_REQUIRES">
10540     <term>
10541       <envar>X_RPM_REQUIRES</envar>
10542     </term>
10543     <listitem><para>
10544 This is used to fill in the
10545 <literal>Requires:</literal>
10546 field in the RPM
10547 <filename>.spec</filename> file.
10548 </para>
10549 </listitem>
10550   </varlistentry>
10551   <varlistentry id="cv-X_RPM_SERIAL">
10552     <term>
10553       <envar>X_RPM_SERIAL</envar>
10554     </term>
10555     <listitem><para>
10556 This is used to fill in the
10557 <literal>Serial:</literal>
10558 field in the RPM
10559 <filename>.spec</filename> file.
10560 </para>
10561 </listitem>
10562   </varlistentry>
10563   <varlistentry id="cv-X_RPM_URL">
10564     <term>
10565       <envar>X_RPM_URL</envar>
10566     </term>
10567     <listitem><para>
10568 This is used to fill in the
10569 <literal>Url:</literal>
10570 field in the RPM
10571 <filename>.spec</filename> file.
10572 </para>
10573 </listitem>
10574   </varlistentry>
10575   <varlistentry id="cv-XGETTEXT">
10576     <term>
10577       <envar>XGETTEXT</envar>
10578     </term>
10579     <listitem><para>
10580 Path to <command>xgettext(1)</command> program (found via
10581 <function>Detect()</function>).
10582 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
10583 </para>
10584 </listitem>
10585   </varlistentry>
10586   <varlistentry id="cv-XGETTEXTCOM">
10587     <term>
10588       <envar>XGETTEXTCOM</envar>
10589     </term>
10590     <listitem><para>
10591 Complete xgettext command line.
10592 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
10593 </para>
10594 </listitem>
10595   </varlistentry>
10596   <varlistentry id="cv-XGETTEXTCOMSTR">
10597     <term>
10598       <envar>XGETTEXTCOMSTR</envar>
10599     </term>
10600     <listitem><para>
10601 A string that is shown when <command>xgettext(1)</command> command is invoked
10602 (default: <literal>''</literal>, which means "print &cv-link-XGETTEXTCOM;").
10603 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
10604 </para>
10605 </listitem>
10606   </varlistentry>
10607   <varlistentry id="cv-_XGETTEXTDOMAIN">
10608     <term>
10609       <envar>_XGETTEXTDOMAIN</envar>
10610     </term>
10611     <listitem><para>
10612 Internal "macro". Generates <command>xgettext</command> domain name
10613 form source and target (default: <literal>'${TARGET.filebase}'</literal>).
10614 </para>
10615 </listitem>
10616   </varlistentry>
10617   <varlistentry id="cv-XGETTEXTFLAGS">
10618     <term>
10619       <envar>XGETTEXTFLAGS</envar>
10620     </term>
10621     <listitem><para>
10622 Additional flags to <command>xgettext(1)</command>.
10623 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
10624 </para>
10625 </listitem>
10626   </varlistentry>
10627   <varlistentry id="cv-XGETTEXTFROM">
10628     <term>
10629       <envar>XGETTEXTFROM</envar>
10630     </term>
10631     <listitem><para>
10632 Name of file containing list of <command>xgettext(1)</command>'s source
10633 files. Autotools' users know this as <filename>POTFILES.in</filename> so they
10634 will in most cases set <literal>XGETTEXTFROM="POTFILES.in"</literal> here.
10635 The &cv-XGETTEXTFROM; files have same syntax and semantics as the well known
10636 GNU <filename>POTFILES.in</filename>.
10637 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
10638 </para>
10639 </listitem>
10640   </varlistentry>
10641   <varlistentry id="cv-_XGETTEXTFROMFLAGS">
10642     <term>
10643       <envar>_XGETTEXTFROMFLAGS</envar>
10644     </term>
10645     <listitem><para>
10646 Internal "macro". Genrates list of <literal>-D&lt;dir&gt;</literal> flags
10647 from the &cv-link-XGETTEXTPATH; list.
10648 </para>
10649 </listitem>
10650   </varlistentry>
10651   <varlistentry id="cv-XGETTEXTFROMPREFIX">
10652     <term>
10653       <envar>XGETTEXTFROMPREFIX</envar>
10654     </term>
10655     <listitem><para>
10656 This flag is used to add single &cv-link-XGETTEXTFROM; file to
10657 <command>xgettext(1)</command>'s commandline (default:
10658 <literal>'-f'</literal>).
10659 </para>
10660 </listitem>
10661   </varlistentry>
10662   <varlistentry id="cv-XGETTEXTFROMSUFFIX">
10663     <term>
10664       <envar>XGETTEXTFROMSUFFIX</envar>
10665     </term>
10666     <listitem><para>
10667 (default: <literal>''</literal>)
10668 </para>
10669 </listitem>
10670   </varlistentry>
10671   <varlistentry id="cv-XGETTEXTPATH">
10672     <term>
10673       <envar>XGETTEXTPATH</envar>
10674     </term>
10675     <listitem><para>
10676 List of directories, there <command>xgettext(1)</command> will look for
10677 source files (default: <literal>[]</literal>).
10678 <note><para>
10679 This variable works only together with &cv-link-XGETTEXTFROM;
10680 </para></note>
10681 See also &t-link-xgettext; tool and &b-link-POTUpdate; builder.
10682 </para>
10683 </listitem>
10684   </varlistentry>
10685   <varlistentry id="cv-_XGETTEXTPATHFLAGS">
10686     <term>
10687       <envar>_XGETTEXTPATHFLAGS</envar>
10688     </term>
10689     <listitem><para>
10690 Internal "macro". Generates list of <literal>-f&lt;file&gt;</literal> flags
10691 from &cv-link-XGETTEXTFROM;.
10692 </para>
10693 </listitem>
10694   </varlistentry>
10695   <varlistentry id="cv-XGETTEXTPATHPREFIX">
10696     <term>
10697       <envar>XGETTEXTPATHPREFIX</envar>
10698     </term>
10699     <listitem><para>
10700 This flag is used to add single search path to
10701 <command>xgettext(1)</command>'s commandline (default:
10702 <literal>'-D'</literal>).
10703 </para>
10704 </listitem>
10705   </varlistentry>
10706   <varlistentry id="cv-XGETTEXTPATHSUFFIX">
10707     <term>
10708       <envar>XGETTEXTPATHSUFFIX</envar>
10709     </term>
10710     <listitem><para>
10711 (default: <literal>''</literal>)
10712 </para>
10713 </listitem>
10714   </varlistentry>
10715   <varlistentry id="cv-YACC">
10716     <term>
10717       <envar>YACC</envar>
10718     </term>
10719     <listitem><para>
10720 The parser generator.
10721 </para>
10722 </listitem>
10723   </varlistentry>
10724   <varlistentry id="cv-YACC_GRAPH_FILE">
10725     <term>
10726       <envar>YACC_GRAPH_FILE</envar>
10727     </term>
10728     <listitem><para>
10729 If supplied, write a graph of the automaton to a file with the name
10730 taken from this variable.
10731 Will be emitted as a <option>--graph=</option>
10732 command-line option. Use this in preference to including
10733 <option>--graph=</option> in &cv-link-YACCFLAGS; directly.
10734 </para>
10735 <para><emphasis>New in version 4.4.0.</emphasis></para>
10736 </listitem>
10737   </varlistentry>
10738   <varlistentry id="cv-YACC_GRAPH_FILE_SUFFIX">
10739     <term>
10740       <envar>YACC_GRAPH_FILE_SUFFIX</envar>
10741     </term>
10742     <listitem><para>
10743 Previously specified by &cv-link-YACCVCGFILESUFFIX;.
10744 </para>
10745 <para>
10746 The suffix of the file
10747 containing a graph of the grammar automaton
10748 when the <option>-g</option> option
10749 (or <option>--graph=</option> without an option-argument)
10750 is used in &cv-link-YACCFLAGS;.
10751 Note that setting this variable informs &SCons;
10752 how to construct the graph filename for tracking purposes,
10753 it does not affect the actual generated filename.
10754 Various yacc tools have emitted various formats
10755 at different times.
10756 Set this to match what your parser generator produces.
10757 </para>
10758 <para><emphasis>New in version 4.6.0</emphasis>. </para>
10759 </listitem>
10760   </varlistentry>
10761   <varlistentry id="cv-YACC_HEADER_FILE">
10762     <term>
10763       <envar>YACC_HEADER_FILE</envar>
10764     </term>
10765     <listitem><para>
10766 If supplied, generate a header file with the name taken from this variable.
10767 Will be emitted as a <option>--header=</option>
10768 command-line option. Use this in preference to including
10769 <option>--header=</option> in &cv-link-YACCFLAGS; directly.
10770 </para>
10771 <para><emphasis>New in version 4.4.0.</emphasis></para>
10772 </listitem>
10773   </varlistentry>
10774   <varlistentry id="cv-YACCCOM">
10775     <term>
10776       <envar>YACCCOM</envar>
10777     </term>
10778     <listitem><para>
10779 The command line used to call the parser generator
10780 to generate a source file.
10781 </para>
10782 </listitem>
10783   </varlistentry>
10784   <varlistentry id="cv-YACCCOMSTR">
10785     <term>
10786       <envar>YACCCOMSTR</envar>
10787     </term>
10788     <listitem><para>
10789 The string displayed when generating a source file
10790 using the parser generator.
10791 If this is not set, then &cv-link-YACCCOM; (the command line) is displayed.
10792 </para>
10793
10794 <example_commands>
10795 env = Environment(YACCCOMSTR="Yacc'ing $TARGET from $SOURCES")
10796 </example_commands>
10797 </listitem>
10798   </varlistentry>
10799   <varlistentry id="cv-YACCFLAGS">
10800     <term>
10801       <envar>YACCFLAGS</envar>
10802     </term>
10803     <listitem><para>
10804 General options passed to the parser generator.
10805 In addition to passing the value on during invocation,
10806 the &t-link-yacc; tool also examines this &consvar; for options
10807 which cause additional output files to be generated,
10808 and adds those to the target list.
10809 </para>
10810
10811 <para>
10812 If the <option>-d</option> option is present in &cv-YACCFLAGS;
10813 &scons; assumes that the call will also create a header file
10814 with the suffix defined by &cv-link-YACCHFILESUFFIX;
10815 if the yacc source file ends in a <filename>.y</filename> suffix,
10816 or a file with the suffix defined by &cv-link-YACCHXXFILESUFFIX;
10817 if the yacc source file ends in a <filename>.yy</filename> suffix.
10818 The header will have the same base name as the requested target.
10819 This is only correct if the executable is <command>bison</command>
10820 (or <command>win_bison</command>).
10821 If using Berkeley yacc (<command>byacc</command>),
10822 <filename>y.tab.h</filename> is always written -
10823 avoid the <option>-d</option> in this case and
10824 use &cv-link-YACC_HEADER_FILE; instead.
10825 </para>
10826
10827 <para>
10828 If a <option>-g</option> option is present,
10829 &scons; assumes that the call will also create a graph file
10830 with the suffix defined by &cv-link-YACCVCGFILESUFFIX;.
10831 </para>
10832
10833 <para>
10834 If a <option>-v</option> option is present,
10835 &scons; assumes that the call will also create an output debug file
10836 with the suffix <filename>.output</filename>.
10837 </para>
10838
10839 <para>
10840 Also recognized are GNU &bison; options
10841 <option>--header</option>
10842 (and its deprecated synonym <option>--defines</option>),
10843 which is similar to
10844 <option>-d</option>
10845 but gives the option to explicitly name the output header file
10846 through an option argument;
10847 and <option>--graph</option>,
10848 which is similar to
10849 <option>-g</option>
10850 but gives the option to explicitly name the output graph file
10851 through an option argument.
10852 The file suffixes described for
10853 <option>-d</option> and <option>-g</option> above
10854 are not applied if these are used in the option=argument form.
10855 </para>
10856
10857 <para>
10858 Note that files specified by <option>--header=</option> and
10859 <option>--graph=</option> may not be properly handled
10860 by &SCons; in all situations, and using those in &cv-YACCFLAGS;
10861 should be considered legacy support only.
10862 Consider using &cv-link-YACC_HEADER_FILE;
10863 and &cv-link-YACC_GRAPH_FILE; instead
10864 if the files need to be explicitly named
10865 (<emphasis>new in version 4.4.0</emphasis>).
10866 </para>
10867 </listitem>
10868   </varlistentry>
10869   <varlistentry id="cv-YACCHFILESUFFIX">
10870     <term>
10871       <envar>YACCHFILESUFFIX</envar>
10872     </term>
10873     <listitem><para>
10874 The suffix of the C
10875 header file generated by the parser generator
10876 when the <option>-d</option> option
10877 (or <option>--header</option> without an option-argument)
10878 is used in &cv-link-YACCFLAGS;.
10879 Note that setting this variable informs &SCons;
10880 how to construct the header filename for tracking purposes,
10881 it does not affect the actual generated filename.
10882 Set this to match what your parser generator produces.
10883 The default value is
10884 <filename>.h</filename>.
10885 </para>
10886 </listitem>
10887   </varlistentry>
10888   <varlistentry id="cv-YACCHXXFILESUFFIX">
10889     <term>
10890       <envar>YACCHXXFILESUFFIX</envar>
10891     </term>
10892     <listitem><para>
10893 The suffix of the C++
10894 header file generated by the parser generator
10895 when the <option>-d</option> option
10896 (or <option>--header</option> without an option-argument)
10897 is used in &cv-link-YACCFLAGS;.
10898 Note that setting this variable informs &SCons;
10899 how to construct the header filename for tracking purposes,
10900 it does not affect the actual generated filename.
10901 Set this to match what your parser generator produces.
10902 The default value is <filename>.hpp</filename>.
10903 </para>
10904 </listitem>
10905   </varlistentry>
10906   <varlistentry id="cv-YACCVCGFILESUFFIX">
10907     <term>
10908       <envar>YACCVCGFILESUFFIX</envar>
10909     </term>
10910     <listitem><para>
10911 Obsoleted. Use &cv-link-YACC_GRAPH_FILE_SUFFIX; instead.
10912 The value is used only if &cv-YACC_GRAPH_FILE_SUFFIX; is not set.
10913 The default value is <filename>.gv</filename>.
10914 </para>
10915 <para>
10916 <emphasis>Changed in version 4.6.0</emphasis>: deprecated. The default value
10917 changed from <filename>.vcg</filename> (&bison; stopped generating
10918 <filename>.vcg</filename> output with version 2.4, in 2006).
10919 </para>
10920 </listitem>
10921   </varlistentry>
10922   <varlistentry id="cv-ZIP">
10923     <term>
10924       <envar>ZIP</envar>
10925     </term>
10926     <listitem><para>
10927 The zip compression and file packaging utility.
10928 </para>
10929 </listitem>
10930   </varlistentry>
10931   <varlistentry id="cv-ZIP_OVERRIDE_TIMESTAMP">
10932     <term>
10933       <envar>ZIP_OVERRIDE_TIMESTAMP</envar>
10934     </term>
10935     <listitem><para>
10936 An optional timestamp which overrides the last modification time of
10937 the file when stored inside the Zip archive. This is a tuple of six values:
10938
10939 Year (&gt;= 1980)
10940 Month (one-based)
10941 Day of month (one-based)
10942 Hours (zero-based)
10943 Minutes (zero-based)
10944 Seconds (zero-based)
10945 </para>
10946 </listitem>
10947   </varlistentry>
10948   <varlistentry id="cv-ZIPCOM">
10949     <term>
10950       <envar>ZIPCOM</envar>
10951     </term>
10952     <listitem><para>
10953 The command line used to call the zip utility,
10954 or the internal Python function used to create a
10955 zip archive.
10956 </para>
10957 </listitem>
10958   </varlistentry>
10959   <varlistentry id="cv-ZIPCOMPRESSION">
10960     <term>
10961       <envar>ZIPCOMPRESSION</envar>
10962     </term>
10963     <listitem><para>
10964 The
10965 <varname>compression</varname>
10966 flag
10967 from the Python
10968 <filename>zipfile</filename>
10969 module used by the internal Python function
10970 to control whether the zip archive
10971 is compressed or not.
10972 The default value is
10973 <literal>zipfile.ZIP_DEFLATED</literal>,
10974 which creates a compressed zip archive.
10975 This value has no effect if the
10976 <literal>zipfile</literal>
10977 module is unavailable.
10978 </para>
10979 </listitem>
10980   </varlistentry>
10981   <varlistentry id="cv-ZIPCOMSTR">
10982     <term>
10983       <envar>ZIPCOMSTR</envar>
10984     </term>
10985     <listitem><para>
10986 The string displayed when archiving files
10987 using the zip utility.
10988 If this is not set, then &cv-link-ZIPCOM;
10989 (the command line or internal Python function) is displayed.
10990 </para>
10991
10992 <example_commands>
10993 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
10994 </example_commands>
10995 </listitem>
10996   </varlistentry>
10997   <varlistentry id="cv-ZIPFLAGS">
10998     <term>
10999       <envar>ZIPFLAGS</envar>
11000     </term>
11001     <listitem><para>
11002 General options passed to the zip utility.
11003 </para>
11004 </listitem>
11005   </varlistentry>
11006   <varlistentry id="cv-ZIPROOT">
11007     <term>
11008       <envar>ZIPROOT</envar>
11009     </term>
11010     <listitem><para>
11011 An optional zip root directory (default empty).  The filenames stored
11012 in the zip file will be relative to this directory, if given.
11013 Otherwise the filenames are relative to the current directory of the
11014 command.
11015 For instance:
11016 </para>
11017 <example_commands>
11018 env = Environment()
11019 env.Zip('foo.zip', 'subdir1/subdir2/file1', ZIPROOT='subdir1')
11020 </example_commands>
11021 <para>
11022 will produce a zip file <literal>foo.zip</literal>
11023 containing a file with the name
11024 <literal>subdir2/file1</literal> rather than
11025 <literal>subdir1/subdir2/file1</literal>.
11026 </para>
11027 </listitem>
11028   </varlistentry>
11029   <varlistentry id="cv-ZIPSUFFIX">
11030     <term>
11031       <envar>ZIPSUFFIX</envar>
11032     </term>
11033     <listitem><para>
11034 The suffix used for zip file names.
11035 </para>
11036 </listitem>
11037   </varlistentry>
11038 </variablelist>