SCons/Defaults.xml

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