SCons/Defaults.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   4 SPDX-License-Identifier: MIT
   5 SPDX-FileType: DOCUMENTATION
   6
   7 This file is processed by the bin/SConsDoc.py module.
   8 -->
   9
  10 <!DOCTYPE sconsdoc [
  11 <!ENTITY % scons SYSTEM '../doc/scons.mod'>
  12 %scons;
  13 <!ENTITY % builders-mod SYSTEM '../doc/generated/builders.mod'>
  14 %builders-mod;
  15 <!ENTITY % functions-mod SYSTEM '../doc/generated/functions.mod'>
  16 %functions-mod;
  17 <!ENTITY % tools-mod SYSTEM '../doc/generated/tools.mod'>
  18 %tools-mod;
  19 <!ENTITY % variables-mod SYSTEM '../doc/generated/variables.mod'>
  20 %variables-mod;
  21 ]>
  22
  23 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  24           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  25           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  26
  27 <cvar name ="_concat">
  28 <summary>
  29     <para>
  30         A function used to produce variables like &cv-link-_CPPINCFLAGS;. It takes
  31         four mandatory arguments, and up to 4 additional optional arguments:
  32         1) a prefix to concatenate onto each element,
  33         2) a list of elements,
  34         3) a suffix to concatenate onto each element,
  35         4) an environment for variable interpolation,
  36         5) an optional function that will be called to transform the list before concatenation,
  37         6) an optionally specified target (Can use TARGET),
  38         7) an optionally specified source (Can use SOURCE),
  39         8) optional <parameter>affect_signature</parameter> flag which will wrap non-empty returned value with $( and $) to indicate the contents
  40         should not affect the signature of the generated command line.
  41     </para>
  42
  43     <example_commands>
  44         env['_CPPINCFLAGS'] = '${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE, affect_signature=False)}'
  45     </example_commands>
  46 </summary>
  47 </cvar>
  48
  49 <cvar name="CONFIGUREDIR">
  50 <summary>
  51 <para>
  52 The name of the directory in which
  53 Configure context test files are written.
  54 The default is
  55 <filename>.sconf_temp</filename>
  56 in the top-level directory
  57 containing the
  58 <filename>SConstruct</filename>
  59 file.
  60 </para>
  61 <para>
  62 If variant directories are in use,
  63 and the configure check results should not be
  64 shared between variants,
  65 you can set &cv-CONFIGUREDIR;
  66 and &cv-link-CONFIGURELOG; so they are
  67 unique per variant directory.
  68 </para>
  69 </summary>
  70 </cvar>
  71
  72 <cvar name="CONFIGURELOG">
  73 <summary>
  74 <para>
  75 The name of the &Configure; context log file.
  76 The default is
  77 <filename>config.log</filename>
  78 in the top-level directory
  79 containing the
  80 <filename>SConstruct</filename>
  81 file.
  82 </para>
  83 <para>
  84 If variant directories are in use,
  85 and the configure check results should not be
  86 shared between variants,
  87 you can set &cv-link-CONFIGUREDIR;
  88 and &cv-CONFIGURELOG; so they are
  89 unique per variant directory.
  90 </para>
  91 </summary>
  92 </cvar>
  93
  94 <cvar name="_CPPDEFFLAGS">
  95 <summary>
  96 <para>
  97 An automatically-generated &consvar;
  98 containing the C preprocessor command-line options
  99 to define values.
 100 The value of &cv-link-_CPPDEFFLAGS; is created
 101 by respectively prepending and appending
 102 &cv-link-CPPDEFPREFIX; and &cv-link-CPPDEFSUFFIX;
 103 to each definition in &cv-link-CPPDEFINES;.
 104 </para>
 105 </summary>
 106 </cvar>
 107
 108 <cvar name="CPPDEFINES">
 109 <summary>
 110 <para>
 111 A platform independent specification of C preprocessor macro definitions.
 112 The definitions are added to command lines
 113 through the automatically-generated
 114 &cv-link-_CPPDEFFLAGS; &consvar;,
 115 which is constructed according to
 116 the contents of &cv-CPPDEFINES;:
 117 </para>
 118
 119 <itemizedlist>
 120 <listitem>
 121 <para>
 122 If &cv-CPPDEFINES; is a string,
 123 the values of the
 124 &cv-link-CPPDEFPREFIX; and &cv-link-CPPDEFSUFFIX; &consvars;
 125 are respectively prepended and appended to
 126 each definition in &cv-CPPDEFINES;,
 127 split on whitespace.
 128 </para>
 129
 130 <example_commands>
 131 # Adds -Dxyz to POSIX compiler command lines,
 132 # and /Dxyz to Microsoft Visual C++ command lines.
 133 env = Environment(CPPDEFINES='xyz')
 134 </example_commands>
 135
 136 </listitem>
 137 <listitem>
 138 <para>
 139 If &cv-CPPDEFINES; is a list,
 140 the values of the
 141 &cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; &consvars;
 142 are respectively prepended and appended to
 143 each element in the list.
 144 If any element is a tuple (or list)
 145 then the first item of the tuple is the macro name
 146 and the second is the macro definition.
 147 If the definition is not omitted or <literal>None</literal>,
 148 the name and definition are combined into a single
 149 <literal>name=definition</literal> item
 150 before the prepending/appending.
 151 </para>
 152
 153 <example_commands>
 154 # Adds -DB=2 -DA to POSIX compiler command lines,
 155 # and /DB=2 /DA to Microsoft Visual C++ command lines.
 156 env = Environment(CPPDEFINES=[('B', 2), 'A'])
 157 </example_commands>
 158
 159 </listitem>
 160 <listitem>
 161 <para>
 162 If &cv-CPPDEFINES; is a dictionary,
 163 the values of the
 164 &cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; &consvars;
 165 are respectively prepended and appended to
 166 each key from the dictionary.
 167 If the value for a key is not <literal>None</literal>,
 168 then the key (macro name) and the value
 169 (macros definition) are combined into a single
 170 <literal>name=definition</literal> item
 171 before the prepending/appending.
 172 </para>
 173
 174 <example_commands>
 175 # Adds -DA -DB=2 to POSIX compiler command lines,
 176 # or /DA /DB=2 to Microsoft Visual C++ command lines.
 177 env = Environment(CPPDEFINES={'B':2, 'A':None})
 178 </example_commands>
 179 </listitem>
 180 </itemizedlist>
 181
 182 <para>
 183 Depending on how contents are added to &cv-CPPDEFINES;,
 184 it may be transformed into a compound type,
 185 for example a list containing strings, tuples and/or dictionaries.
 186 &SCons; can correctly expand such a compound type.
 187 </para>
 188
 189 <para>
 190 Note that &SCons; may call the compiler via a shell.
 191 If a macro definition contains characters such as spaces that
 192 have meaning to the shell, or is intended to be a string value,
 193 you may need to use the shell's quoting syntax to avoid
 194 interpretation by the shell before the preprocessor sees it.
 195 Function-like macros are not supported via this mechanism
 196 (and some compilers do not even implement that functionality
 197 via the command lines).
 198 When quoting, note that
 199 one set of quote characters are used to define a &Python; string,
 200 then quotes embedded inside that would be consumed by the shell
 201 unless escaped.  These examples may help illustrate:
 202 </para>
 203
 204 <example_commands>
 205 env = Environment(CPPDEFINES=['USE_ALT_HEADER=\\"foo_alt.h\\"'])
 206 env = Environment(CPPDEFINES=[('USE_ALT_HEADER', '\\"foo_alt.h\\"')])
 207 </example_commands>
 208
 209 <para>
 210 :<emphasis>Changed in version  4.5</emphasis>:
 211 &SCons; no longer sorts &cv-CPPDEFINES; values entered
 212 in dictionary form.  &Python; now preserves dictionary
 213 keys in the order they are entered, so it is no longer
 214 necessary to sort them to ensure a stable command line.
 215 </para>
 216
 217 </summary>
 218 </cvar>
 219
 220 <cvar name="CPPDEFPREFIX">
 221 <summary>
 222 <para>
 223 The prefix used to specify preprocessor macro definitions
 224 on the C compiler command line.
 225 This will be prepended to each definition
 226 in the &cv-link-CPPDEFINES; &consvar;
 227 when the &cv-link-_CPPDEFFLAGS; variable is automatically generated.
 228 </para>
 229 </summary>
 230 </cvar>
 231
 232 <cvar name="CPPDEFSUFFIX">
 233 <summary>
 234 <para>
 235 The suffix used to specify preprocessor macro definitions
 236 on the C compiler command line.
 237 This will be appended to each definition
 238 in the &cv-link-CPPDEFINES; &consvar;
 239 when the &cv-link-_CPPDEFFLAGS; variable is automatically generated.
 240 </para>
 241 </summary>
 242 </cvar>
 243
 244 <cvar name="_CPPINCFLAGS">
 245 <summary>
 246 <para>
 247 An automatically-generated &consvar;
 248 containing the C preprocessor command-line options
 249 for specifying directories to be searched for include files.
 250 The value of &cv-_CPPINCFLAGS; is created
 251 by respectively prepending and appending
 252 &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
 253 to each directory in &cv-link-CPPPATH;.
 254 </para>
 255 </summary>
 256 </cvar>
 257
 258 <cvar name="CPPPATH">
 259 <summary>
 260 <para>
 261 The list of directories that the C preprocessor will search for include
 262 directories. The C/C++ implicit dependency scanner will search these
 263 directories for include files.
 264 In general, it's not advised to put include directory directives
 265 directly into &cv-link-CCFLAGS; or &cv-link-CXXFLAGS;
 266 as the result will be non-portable
 267 and the directories will not be searched by the dependency scanner.
 268 &cv-CPPPATH; should be a list of path strings,
 269 or a single string, not a pathname list joined by
 270 Python's <systemitem>os.pathsep</systemitem>.
 271 </para>
 272
 273 <para>
 274 Note:
 275 directory names in &cv-CPPPATH;
 276 will be looked-up relative to the directory of the SConscript file
 277 when they are used in a command.
 278 To force &scons;
 279 to lookup a directory relative to the root of the source tree, use
 280 the <literal>#</literal> prefix:
 281 </para>
 282
 283 <example_commands>
 284 env = Environment(CPPPATH='#/include')
 285 </example_commands>
 286
 287 <para>
 288 The directory lookup can also be forced using the
 289 &f-link-Dir;
 290 function:
 291 </para>
 292
 293 <example_commands>
 294 include = Dir('include')
 295 env = Environment(CPPPATH=include)
 296 </example_commands>
 297
 298 <para>
 299 The directory list will be added to command lines
 300 through the automatically-generated
 301 &cv-link-_CPPINCFLAGS; &consvar;,
 302 which is constructed by
 303 respectively prepending and appending the values of the
 304 &cv-link-INCPREFIX; and &cv-link-INCSUFFIX; &consvars;
 305 to each directory in &cv-link-CPPPATH;.
 306 Any command lines you define that need
 307 the &cv-CPPPATH; directory list should
 308 include &cv-link-_CPPINCFLAGS;:
 309 </para>
 310
 311 <example_commands>
 312 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
 313 </example_commands>
 314 </summary>
 315 </cvar>
 316
 317 <cvar name="Dir">
 318 <summary>
 319 <para>
 320 A function that converts a string
 321 into a Dir instance relative to the target being built.
 322 </para>
 323 </summary>
 324 </cvar>
 325
 326 <cvar name="Dirs">
 327 <summary>
 328 <para>
 329 A function that converts a list of strings
 330 into a list of Dir instances relative to the target being built.
 331 </para>
 332 </summary>
 333 </cvar>
 334
 335 <cvar name="DSUFFIXES">
 336 <summary>
 337 <para>
 338 The list of suffixes of files that will be scanned
 339 for imported D package files.
 340 The default list is <literal>['.d']</literal>.
 341 </para>
 342 </summary>
 343 </cvar>
 344
 345 <cvar name="File">
 346 <summary>
 347 <para>
 348 A function that converts a string into a File instance relative to the
 349 target being built.
 350 </para>
 351 </summary>
 352 </cvar>
 353
 354 <cvar name="IDLSUFFIXES">
 355 <summary>
 356 <para>
 357 The list of suffixes of files that will be scanned
 358 for IDL implicit dependencies
 359 (#include or import lines).
 360 The default list is:
 361 </para>
 362
 363 <example_commands>
 364 [".idl", ".IDL"]
 365 </example_commands>
 366 </summary>
 367 </cvar>
 368
 369 <cvar name="INCPREFIX">
 370 <summary>
 371 <para>
 372 The prefix used to specify an include directory on the C compiler command
 373 line.
 374 This will be prepended to each directory
 375 in the &cv-link-CPPPATH; and &cv-link-FORTRANPATH; &consvars;
 376 when the &cv-link-_CPPINCFLAGS; and &cv-link-_FORTRANINCFLAGS;
 377 variables are automatically generated.
 378 </para>
 379 </summary>
 380 </cvar>
 381
 382 <cvar name="INCSUFFIX">
 383 <summary>
 384 <para>
 385 The suffix used to specify an include directory on the C compiler command
 386 line.
 387 This will be appended to each directory
 388 in the &cv-link-CPPPATH; and &cv-link-FORTRANPATH; &consvars;
 389 when the &cv-link-_CPPINCFLAGS; and &cv-link-_FORTRANINCFLAGS;
 390 variables are automatically generated.
 391 </para>
 392 </summary>
 393 </cvar>
 394
 395 <cvar name="INSTALL">
 396 <summary>
 397 <para>
 398 A function to be called to install a file into a
 399 destination file name.
 400 The default function copies the file into the destination
 401 (and sets the destination file's mode and permission bits
 402 to match the source file's).
 403 The function takes the following arguments:
 404 </para>
 405
 406 <example_commands>
 407 def install(dest, source, env):
 408 </example_commands>
 409
 410 <para>
 411 <varname>dest</varname>
 412 is the path name of the destination file.
 413 <varname>source</varname>
 414 is the path name of the source file.
 415 <varname>env</varname>
 416 is the construction environment
 417 (a dictionary of construction values)
 418 in force for this file installation.
 419 </para>
 420 </summary>
 421 </cvar>
 422
 423 <cvar name="INSTALLSTR">
 424 <summary>
 425 <para>
 426 The string displayed when a file is
 427 installed into a destination file name.
 428 The default is:
 429 </para>
 430 <example_commands>
 431 Install file: "$SOURCE" as "$TARGET"
 432 </example_commands>
 433 </summary>
 434 </cvar>
 435
 436 <cvar name="LATEXSUFFIXES">
 437 <summary>
 438 <para>
 439 The list of suffixes of files that will be scanned
 440 for LaTeX implicit dependencies
 441 (<literal>\include</literal> or <literal>\import</literal> files).
 442 The default list is:
 443 </para>
 444
 445 <example_commands>
 446 [".tex", ".ltx", ".latex"]
 447 </example_commands>
 448 </summary>
 449 </cvar>
 450
 451 <cvar name="_LIBDIRFLAGS">
 452 <summary>
 453 <para>
 454 An automatically-generated construction variable
 455 containing the linker command-line options
 456 for specifying directories to be searched for library.
 457 The value of &cv-_LIBDIRFLAGS; is created
 458 by respectively prepending and appending &cv-link-LIBDIRPREFIX;
 459 and &cv-link-LIBDIRSUFFIX;
 460 to each directory in &cv-link-LIBPATH;.
 461 </para>
 462 </summary>
 463 </cvar>
 464
 465 <cvar name="LIBDIRPREFIX">
 466 <summary>
 467 <para>
 468 The prefix used to specify a library directory on the linker command line.
 469 This will be prepended to each directory
 470 in the &cv-link-LIBPATH; construction variable
 471 when the &cv-link-_LIBDIRFLAGS; variable is automatically generated.
 472 </para>
 473 </summary>
 474 </cvar>
 475
 476 <cvar name="LIBDIRSUFFIX">
 477 <summary>
 478 <para>
 479 The suffix used to specify a library directory on the linker command line.
 480 This will be appended to each directory
 481 in the &cv-link-LIBPATH; construction variable
 482 when the &cv-link-_LIBDIRFLAGS; variable is automatically generated.
 483 </para>
 484 </summary>
 485 </cvar>
 486
 487 <cvar name="_LIBFLAGS">
 488 <summary>
 489 <para>
 490 An automatically-generated construction variable
 491 containing the linker command-line options
 492 for specifying libraries to be linked with the resulting target.
 493 The value of &cv-_LIBFLAGS; is created
 494 by respectively prepending and appending &cv-link-LIBLINKPREFIX;
 495 and &cv-link-LIBLINKSUFFIX;
 496 to each filename in &cv-link-LIBS;.
 497 </para>
 498 </summary>
 499 </cvar>
 500
 501 <cvar name="LIBLINKPREFIX">
 502 <summary>
 503 <para>
 504 The prefix used to specify a library to link on the linker command line.
 505 This will be prepended to each library
 506 in the &cv-link-LIBS; construction variable
 507 when the &cv-link-_LIBFLAGS; variable is automatically generated.
 508 </para>
 509 </summary>
 510 </cvar>
 511
 512 <cvar name="LIBLINKSUFFIX">
 513 <summary>
 514 <para>
 515 The suffix used to specify a library to link on the linker command line.
 516 This will be appended to each library
 517 in the &cv-link-LIBS; construction variable
 518 when the &cv-link-_LIBFLAGS; variable is automatically generated.
 519 </para>
 520 </summary>
 521 </cvar>
 522
 523 <cvar name="LIBPATH">
 524 <summary>
 525 <para>
 526 The list of directories that will be searched for libraries
 527 specified by the &cv-link-LIBS; &consvar;.
 528 &cv-LIBPATH; should be a list of path strings,
 529 or a single string, not a pathname list joined by
 530 Python's <systemitem>os.pathsep</systemitem>.
 531 <!-- XXX OLD
 532 The implicit dependency scanner will search these
 533 directories for include files. Don't explicitly put include directory
 534 arguments into &cv-LINKFLAGS; or &cv-SHLINKFLAGS;
 535 because the result will be non-portable
 536 and the directories will not be searched by the dependency scanner.
 537 -->
 538 <!-- XXX NEW -->
 539 Do not put library search directives directly
 540 into &cv-LINKFLAGS; or &cv-SHLINKFLAGS;
 541 as the result will be non-portable.
 542 <!-- end NEW -->
 543 </para>
 544
 545 <para>
 546 Note:
 547 directory names in &cv-LIBPATH; will be looked-up relative to the
 548 directory of the SConscript file
 549 when they are used in a command.
 550 To force &scons;
 551 to lookup a directory relative to the root of the source tree, use
 552 the <literal>#</literal> prefix:
 553 </para>
 554
 555 <example_commands>
 556 env = Environment(LIBPATH='#/libs')
 557 </example_commands>
 558
 559 <para>
 560 The directory lookup can also be forced using the
 561 &f-link-Dir; function:
 562 </para>
 563
 564 <example_commands>
 565 libs = Dir('libs')
 566 env = Environment(LIBPATH=libs)
 567 </example_commands>
 568
 569 <para>
 570 The directory list will be added to command lines
 571 through the automatically-generated
 572 &cv-link-_LIBDIRFLAGS;
 573 construction variable,
 574 which is constructed by
 575 respectively prepending and appending the values of the
 576 &cv-link-LIBDIRPREFIX; and &cv-link-LIBDIRSUFFIX;
 577 construction variables
 578 to each directory in &cv-LIBPATH;.
 579 Any command lines you define that need
 580 the &cv-LIBPATH; directory list should
 581 include &cv-_LIBDIRFLAGS;:
 582 </para>
 583
 584 <example_commands>
 585 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
 586 </example_commands>
 587 </summary>
 588 </cvar>
 589
 590 <cvar name="LIBS">
 591 <summary>
 592 <para>
 593 The list of libraries
 594 that will be added to the link line
 595 for linking with any executable program, shared library, or loadable module
 596 created by the &consenv; or override.
 597 </para>
 598
 599 <para>
 600 For portability,
 601 a string-valued library name should include
 602 only the base library name,
 603 without prefixes such as <filename>lib</filename>
 604 or suffixes such as <filename>.so</filename> or <filename>.dll</filename>.
 605 &SCons; <emphasis>will</emphasis> attempt to
 606 strip prefixes from the &cv-link-LIBPREFIXES; list
 607 and suffixes from the &cv-link-LIBSUFFIXES; list,
 608 but depending on that behavior will make the build
 609 less portable:
 610 for example, on a POSIX system,
 611 no attempt will be made to strip a suffix like
 612 <filename>.dll</filename>.
 613 Library name strings in &cv-LIBS; should not include a path component:
 614 instead use &cv-link-LIBPATH; to direct the compiler
 615 to look for libraries in those paths,
 616 plus any default paths the linker searches in.
 617 If &cv-link-LIBLITERALPREFIX; is set to a non-empty string,
 618 then a string-valued &cv-LIBS; entry
 619 that starts with &cv-link-LIBLITERALPREFIX;
 620 will cause the rest of the entry
 621 to be searched for unmodified,
 622 but respecting normal library search paths
 623 (this is an exception to the guideline above
 624 about leaving off the prefix/suffix from the library name).
 625 </para>
 626
 627 <para>
 628 If a &cv-LIBS; entry is a Node object
 629 (either as returned by a previous Builder call,
 630 or as the result of an explicit call to &f-link-File;),
 631 the pathname from that Node will be added to
 632 &cv-_LIBFLAGS;,
 633 and thus to the link line,
 634 unmodified - without adding
 635 &cv-LIBLINKPREFIX;
 636 or
 637 &cv-LIBLINKSUFFIX;.
 638 Such entries are searched for literally
 639 (including any path component);
 640 the library search paths are not used.
 641 For example:
 642 </para>
 643
 644 <example_commands>
 645 env.Append(LIBS=File('/tmp/mylib.so'))
 646 </example_commands>
 647
 648 <para>
 649 <!-- is this actually true? -->
 650 For each &Builder; call that causes linking with libraries,
 651 &SCons; will add the libraries in the setting of &cv-LIBS;
 652 in effect at that moment to the dependency graph
 653 as dependencies of the target being generated.
 654 </para>
 655
 656 <para>
 657 The library list will be transformed to command-line
 658 arguments through the automatically-generated
 659 &cv-link-_LIBFLAGS; &consvar;
 660 which is constructed by
 661 respectively prepending and appending the values of the
 662 &cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX; &consvars;
 663 to each library name.
 664 </para>
 665
 666 <para>
 667 Any command lines you define yourself that need
 668 the libraries from &cv-LIBS; should include &cv-_LIBFLAGS;
 669 (as well as &cv-link-_LIBDIRFLAGS;)
 670 rather than &cv-LIBS;.
 671 For example:
 672 </para>
 673
 674 <example_commands>
 675 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
 676 </example_commands>
 677 </summary>
 678 </cvar>
 679
 680 <cvar name="LIBLITERALPREFIX">
 681 <summary>
 682 <para>
 683 If the linker supports command line syntax directing
 684 that the argument specifying a library should be
 685 searched for literally (without modification),
 686 &cv-LIBLITERALPREFIX; can be set to that indicator.
 687 For example, the GNU linker follows this rule:
 688 <quote>
 689 <literal>-l:foo</literal> searches the library path
 690 for a filename called <literal>foo</literal>,
 691 without converting it to
 692 <literal>libfoo.so</literal> or
 693 <literal>libfoo.a</literal>.
 694 </quote>
 695 If &cv-LIBLITERALPREFIX; is set,
 696 &SCons; will not transform a string-valued entry in
 697 &cv-link-LIBS; that starts with that string.
 698 The entry will still be surrounded with
 699 &cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX;
 700 on the command line.
 701 This is useful, for example,
 702 in directing that a static library
 703 be used when both a static and dynamic library are available
 704 and linker policy is to prefer dynamic libraries.
 705 Compared to the example in &cv-link-LIBS;,
 706 </para>
 707 <example_commands>
 708 env.Append(LIBS=":libmylib.a")
 709 </example_commands>
 710 <para>
 711 will let the linker select that specific (static)
 712 library name if found in the library search path.
 713 This differs from using a
 714 <classname>File</classname> object
 715 to specify the static library,
 716 as the latter bypasses the library search path entirely.
 717 </para>
 718 </summary>
 719 </cvar>
 720
 721 <cvar name="RDirs">
 722 <summary>
 723 <para>
 724 A function that converts a string into a list of Dir instances by
 725 searching the repositories.
 726 </para>
 727 </summary>
 728 </cvar>
 729
 730 <scons_function name="DefaultEnvironment">
 731 <arguments signature="global">
 732 ([key=value, ...])
 733 </arguments>
 734 <summary>
 735 <para>
 736 Instantiates and returns the global &consenv; object.
 737 The <firstterm>&DefEnv;</firstterm> is used internally by &SCons;
 738 when executing a global function
 739 or the global form of a Builder method
 740 that requires access to a &consenv;.
 741 </para>
 742
 743 <para>
 744 On the first call,
 745 arguments are interpreted as for the &f-link-Environment; function.
 746 The &DefEnv; is a singleton;
 747 subsequent calls to &f-DefaultEnvironment; return
 748 the already-constructed object,
 749 and any keyword arguments are silently ignored.
 750 </para>
 751
 752 <para>
 753 The &DefEnv; can be modified after instantiation,
 754 similar to other &consenvs;,
 755 although some &consenv; methods may be unavailable.
 756 Modifying the &DefEnv; has no effect on any other &consenv;,
 757 either existing or newly constructed.
 758 </para>
 759
 760 <para>
 761 It is not necessary to explicitly call &f-DefaultEnvironment;.
 762 &SCons; instantiates the &defenv; automatically when the
 763 build phase begins, if has not already been done.
 764 However, calling it explicitly provides the opportunity to
 765 affect and examine its contents.
 766 Instantiation occurs even if nothing in the build system
 767 appears to use it, due to internal uses.
 768 </para>
 769
 770 <para>
 771 If the project &SConscript; files do not use global functions or Builders,
 772 a small performance gain may be achieved by calling
 773 &f-DefaultEnvironment; with an empty tools list
 774 (<userinput>DefaultEnvironment(tools=[])</userinput>).
 775 This avoids the tool initialization cost for the &DefEnv;,
 776 which is mainly of interest in the test suite
 777 where &scons; is launched repeatedly in a short time period.
 778 </para>
 779 </summary>
 780 </scons_function>
 781
 782 </sconsdoc>