[ci skip] update generated files
[scons.git] / doc / generated / functions.gen
blob9668af818f64dc46dc8e8345f93a885d9cb93f44
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;
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="f-Action">
16     <term><function>Action</function>(<parameter>action, [output, [var, ...]] [key=value, ...]</parameter>)</term>
17     <term><replaceable>env</replaceable>.<methodname>Action</methodname>(<parameter>action, [output, [var, ...]] [key=value, ...]</parameter>)</term>
18     <listitem><para>
19 A factory function to create an Action object for
20 the specified
21 <parameter>action</parameter>.
22 See the manpage section "Action Objects"
23 for a complete explanation of the arguments and behavior.
24 </para>
26 <para>
27 Note that the &f-env-Action;
28 form of the invocation will expand
29 &consvars; in any argument strings,
30 including the
31 <parameter>action</parameter>
32 argument, at the time it is called
33 using the &consvars; in the
34 &consenv; through which
35 &f-env-Action; was called.
36 The &f-Action; global function
37 form delays all variable expansion
38 until the Action object is actually used.
39 </para>
40 </listitem>
41   </varlistentry>
42   <varlistentry id="f-AddMethod">
43     <term><function>AddMethod</function>(<parameter>object, function, [name]</parameter>)</term>
44     <term><replaceable>env</replaceable>.<methodname>AddMethod</methodname>(<parameter>function, [name]</parameter>)</term>
45     <listitem><para>
46 Adds <parameter>function</parameter> to an object as a method.
47 <parameter>function</parameter> will be called with an instance
48 object as the first argument as for other methods.
49 If <parameter>name</parameter> is given, it is used as
50 the name of the new method, else the name of
51 <parameter>function</parameter> is used.
52 </para>
53 <para>
54 When the global function &f-AddMethod; is called,
55 the object to add the method to must be passed as the first argument;
56 typically this will be &Environment;,
57 in order to create a method which applies to all &consenvs;
58 subsequently constructed.
59 When called using the &f-env-AddMethod; form,
60 the method is added to the specified &consenv; only.
61 Added methods propagate through &f-env-Clone; calls.
62 </para>
64 <para>
65 More examples:
66 </para>
68 <example_commands>
69 # Function to add must accept an instance argument.
70 # The Python convention is to call this 'self'.
71 def my_method(self, arg):
72     print("my_method() got", arg)
74 # Use the global function to add a method to the Environment class:
75 AddMethod(Environment, my_method)
76 env = Environment()
77 env.my_method('arg')
79 # Use the optional name argument to set the name of the method:
80 env.AddMethod(my_method, 'other_method_name')
81 env.other_method_name('another arg')
82 </example_commands>
83 </listitem>
84   </varlistentry>
85   <varlistentry id="f-AddOption">
86     <term><function>AddOption</function>(<parameter>opt_str, ..., attr=value, ...</parameter>)</term>
87     <listitem><para>
88 Adds a local (project-specific) command-line option.
89 One or more <parameter>opt_str</parameter> values are
90 the strings representing how the option can be called,
91 while the keyword arguments define attributes of the option.
92 For the most part these are the same as for the
93 <function>OptionParser.add_option</function>
94 method in the standard Python library module
95 <systemitem>optparse</systemitem>,
96 but with a few additional capabilities noted below.
97 See the
98 <ulink url="https://docs.python.org/3/library/optparse.html">
99 optparse documentation</ulink>
100 for a thorough discussion of its option-processing capabilities.
101 All options added through &f-AddOption; are placed
102 in a special "Local Options" option group.
103 </para>
105 <para>
106 In addition to the arguments and values supported by the
107 <systemitem>optparse</systemitem>
108 <function>add_option</function>
109 method, &f-AddOption;
110 allows setting the
111 <parameter>nargs</parameter>
112 keyword value to
113 a string <literal>'?'</literal> (question mark)
114 to indicate that the option argument for
115 that option string may be omitted.
116 If the option string is present on the
117 command line but has no matching option
118 argument, the value of the
119 <parameter>const</parameter>
120 keyword argument is produced as the value
121 of the option.
122 If the option string is omitted from
123 the command line, the value of the
124 <parameter>default</parameter>
125 keyword argument is produced, as usual;
126 if there is no
127 <parameter>default</parameter>
128 keyword argument in the &f-AddOption; call,
129 <constant>None</constant> is produced.
130 </para>
132 <para>
133 <systemitem>optparse</systemitem> recognizes
134 abbreviations of long option names,
135 as long as they can be unambiguously resolved.
136 For example, if
137 <function>add_option</function> is called to
138 define a <option>--devicename</option> option,
139 it will recognize <option>--device</option>,
140 <option>--dev</option>
141 and so forth as long as there is no other option
142 which could also match to the same abbreviation.
143 Options added via
144 &f-AddOption; do not support
145 the automatic recognition of abbreviations.
146 Instead, to allow specific abbreviations,
147 include them as synonyms in the &f-AddOption; call itself.
148 </para>
150 <para>
151 Once a new command-line option has been added with
152 &f-AddOption;,
153 the option value may be accessed using
154 &f-link-GetOption;
156 &f-link-env-GetOption;.
157 If the <parameter>settable=True</parameter> argument
158 was supplied in the &AddOption; call,
159 the value may also be set later using
160 &f-link-SetOption;
162 &f-link-env-SetOption;,
163 if conditions in an
164 &SConscript; file
165 require overriding any default value.
166 Note however that a
167 value specified on the command line will
168 <emphasis>always</emphasis>
169 override a value set in an SConscript file.
170 </para>
172 <para>
173 <emphasis>Changed in 4.8.0</emphasis>: added the
174 <parameter>settable</parameter> keyword argument
175 to enable an added option to be settable via &SetOption;.
176 </para>
178 <para>
179 Help text for an option is a combination
180 of the string supplied in the
181 <parameter>help</parameter> keyword
182 argument to &f-AddOption; and information
183 collected from the other keyword arguments.
184 Such help is displayed if the
185 <option>-h</option> command line option
186 is used (but not with <option>-H</option>).
187 Help for all local options is displayed
188 under the separate heading
189 <emphasis role="bold">Local Options</emphasis>.
190 The options are unsorted - they will appear
191 in the help text in the order in which the
192 &f-AddOption;
193 calls occur.
194 </para>
196 <para>
197 Example:
198 </para>
200 <example_commands>
201 AddOption(
202     '--prefix',
203     dest='prefix',
204     nargs=1,
205     type='string',
206     action='store',
207     metavar='DIR',
208     help='installation prefix',
210 env = Environment(PREFIX=GetOption('prefix'))
211 </example_commands>
213 <para>For that example,
214 the following help text would be produced:</para>
216 <screen>
217 Local Options:
218   --prefix=DIR                installation prefix
219 </screen>
221 <para>
222 Help text for local options may be unavailable if
223 the &f-link-Help; function has been called,
224 see the &f-Help; documentation for details.
225 </para>
227 <note>
228 <para>
229 As an artifact of the internal implementation,
230 the behavior of options added by &AddOption;
231 which take option arguments is undefined
232 <emphasis>if</emphasis> whitespace
233 (rather than an <literal>=</literal> sign) is used as
234 the separator on the command line.
235 Users should avoid such usage; it is recommended
236 to add a note to this effect to project documentation
237 if the situation is likely to arise.
238 In addition, if the <parameter>nargs</parameter>
239 keyword is used to specify more than one following
240 option argument (that is, with a value of <constant>2</constant>
241 or greater), such arguments would necessarily
242 be whitespace separated, triggering the issue.
243 Developers should not use &AddOption; this way.
244 Future versions of &SCons; will likely forbid such usage.
245 </para>
246 </note>
248 </listitem>
249   </varlistentry>
250   <varlistentry id="f-AddPostAction">
251     <term><function>AddPostAction</function>(<parameter>target, action</parameter>)</term>
252     <term><replaceable>env</replaceable>.<methodname>AddPostAction</methodname>(<parameter>target, action</parameter>)</term>
253     <listitem><para>
254 Arranges for the specified
255 <parameter>action</parameter>
256 to be performed
257 after the specified
258 <parameter>target</parameter>
259 has been built.
260 <parameter>action</parameter> may be
261 an Action object, or anything that
262 can be converted into an Action object.
263 See the manpage section "Action Objects"
264 for a complete explanation.
265 </para>
267 <para>
268 When multiple targets are supplied,
269 the action may be called multiple times,
270 once after each action that generates
271 one or more targets in the list.
272 </para>
274 <example_commands>
275 foo = Program('foo.c')
276 # remove execute permission from binary:
277 AddPostAction(foo, Chmod('$TARGET', "a-x"))
278 </example_commands>
280 </listitem>
281   </varlistentry>
282   <varlistentry id="f-AddPreAction">
283     <term><function>AddPreAction</function>(<parameter>target, action</parameter>)</term>
284     <term><replaceable>env</replaceable>.<methodname>AddPreAction</methodname>(<parameter>target, action</parameter>)</term>
285     <listitem><para>
286 Arranges for the specified
287 <parameter>action</parameter>
288 to be performed
289 before the specified
290 <parameter>target</parameter>
291 is built.
292 <parameter>action</parameter> may be
293 an Action object, or anything that
294 can be converted into an Action object.
295 See the manpage section "Action Objects"
296 for a complete explanation.
297 </para>
299 <para>
300 When multiple targets are specified,
301 the action(s) may be called multiple times,
302 once before each action that generates
303 one or more targets in the list.
304 </para>
306 <para>
307 Note that if any of the targets are built in multiple steps,
308 the action will be invoked just
309 before the "final" action that specifically
310 generates the specified target(s).
311 For example, when building an executable program
312 from a specified source
313 <filename>.c</filename>
314 file via an intermediate object file:
315 </para>
317 <example_commands>
318 foo = Program('foo.c')
319 AddPreAction(foo, 'pre_action')
320 </example_commands>
322 <para>
323 The specified
324 <literal>pre_action</literal>
325 would be executed before
326 &scons;
327 calls the link command that actually
328 generates the executable program binary
329 <filename>foo</filename>,
330 not before compiling the
331 <filename>foo.c</filename>
332 file into an object file.
333 </para>
334 </listitem>
335   </varlistentry>
336   <varlistentry id="f-Alias">
337     <term><function>Alias</function>(<parameter>alias, [source, [action]]</parameter>)</term>
338     <term><replaceable>env</replaceable>.<methodname>Alias</methodname>(<parameter>alias, [source, [action]]</parameter>)</term>
339     <listitem><para>
340 Creates an <firstterm>alias</firstterm> target that
341 can be used as a reference to zero or more other targets,
342 specified by the optional <parameter>source</parameter> parameter.
343 Aliases provide a way to give a shorter or more descriptive
344 name to specific targets,
345 and to group multiple targets under a single name.
346 The alias name, or an Alias Node object,
347 may be used as a dependency of any other target,
348 including another alias.
349 </para>
351 <para>
352 <parameter>alias</parameter> and <parameter>source</parameter>
353 may each be a string or Node object,
354 or a list of strings or Node objects;
355 if Nodes are used for
356 <parameter>alias</parameter>
357 they must be Alias nodes.
358 If <parameter>source</parameter> is omitted,
359 the alias is created but has no reference;
360 if selected for building this will result in a
361 <quote>Nothing to be done.</quote> message.
362 An empty alias can be used to define the alias
363 in a visible place in the project;
364 it can later be appended to in a subsidiary SConscript file
365 with the actual target(s) to refer to.
366 The optional
367 <parameter>action</parameter>
368 parameter specifies an action or list of actions
369 that will be executed
370 whenever the any of the alias targets are out-of-date.
371 </para>
373 <para>
374 &f-Alias; can be called for an existing alias,
375 which appends the <parameter>alias</parameter>
376 and/or <parameter>action</parameter> arguments
377 to the existing lists for that alias.
378 </para>
380 <para>
381 Returns a list of Alias Node objects representing the alias(es),
382 which exist outside of any physical file system.
383 The alias name space is separate from the name space for
384 tangible targets; to avoid confusion do not reuse
385 target names as alias names.
386 </para>
388 <para>
389 Examples:
390 </para>
392 <example_commands>
393 Alias('install')
394 Alias('install', '/usr/bin')
395 Alias(['install', 'install-lib'], '/usr/local/lib')
397 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
398 env.Alias('install', ['/usr/local/man'])
400 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
401 </example_commands>
402 </listitem>
403   </varlistentry>
404   <varlistentry id="f-AllowSubstExceptions">
405     <term><function>AllowSubstExceptions</function>(<parameter>[exception, ...]</parameter>)</term>
406     <listitem><para>
407 Specifies the exceptions that will be ignored
408 when expanding &consvars;.
409 By default,
410 any &consvar; expansions that generate a
411 &NameError;
413 &IndexError;
414 exception will expand to a
415 <literal>''</literal>
416 (an empty string) and not cause &scons; to fail.
417 All exceptions not in the specified list
418 will generate an error message
419 and terminate processing.
420 </para>
422 <para>
424 &f-AllowSubstExceptions;
425 is called multiple times,
426 each call completely overwrites the previous list
427 of ignored exceptions.
428 Calling it with no arguments means no exceptions will be ignored.
429 </para>
431 <para>
432 Example:
433 </para>
435 <example_commands>
436 # Requires that all construction variable names exist.
437 # (You may wish to do this if you want to enforce strictly
438 # that all construction variables must be defined before use.)
439 AllowSubstExceptions()
441 # Also allow a string containing a zero-division expansion
442 # like '${1 / 0}' to evaluate to ''.
443 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
444 </example_commands>
445 </listitem>
446   </varlistentry>
447   <varlistentry id="f-AlwaysBuild">
448     <term><function>AlwaysBuild</function>(<parameter>target, ...</parameter>)</term>
449     <term><replaceable>env</replaceable>.<methodname>AlwaysBuild</methodname>(<parameter>target, ...</parameter>)</term>
450     <listitem><para>
451 Marks each given
452 <parameter>target</parameter>
453 so that it is always assumed to be out-of-date,
454 and will always be rebuilt if needed.
455 Note, however, that
456 &f-AlwaysBuild;
457 does not add its target(s) to the default target list,
458 so the targets will only be built
459 if they are specified on the command line,
460 or are a dependent of a target specified on the command line--but
461 they will
462 <emphasis>always</emphasis>
463 be built if so specified.
464 Multiple targets can be passed in to a single call to
465 &f-AlwaysBuild;.
466 </para>
467 </listitem>
468   </varlistentry>
469   <varlistentry id="f-Append">
470     <term><replaceable>env</replaceable>.<methodname>Append</methodname>(<parameter>key=val, [...]</parameter>)</term>
471     <listitem><para>
472 Appends value(s) intelligently to &consvars; in
473 <varname>env</varname>.
474 The &consvars; and values to add to them are passed as
475 <parameter>key=val</parameter> pairs (&Python; keyword arguments).
476 &f-env-Append; is designed to allow adding values
477 without having to think about the data type of an existing &consvar;.
478 Regular &Python; syntax can also be used to manipulate the &consvar;,
479 but for that you may need to know the types involved,
480 for example pure &Python; lets you directly "add" two lists of strings,
481 but adding a string to a list or a list to a string requires
482 different syntax - things &f-Append; takes care of.
483 Some pre-defined &consvars; do have type expectations
484 based on how &SCons; will use them:
485 for example &cv-link-CPPDEFINES; is often a string or a list of strings,
486 but can also be a list of tuples or a dictionary;
487 while &cv-link-LIBEMITTER;
488 is expected to be a callable or list of callables,
489 and &cv-link-BUILDERS; is expected to be a dictionary.
490 Consult the documentation for the various &consvars; for more details.
491 </para>
493 <para>
494 The following descriptions apply to both the &f-Append;
495 and &f-Prepend; methods, as well as their
496 <emphasis role="bold">Unique</emphasis> variants,
497 with the differences being the insertion point of the added values
498 and whether duplication is allowed.
499 </para>
501 <para>
502 <parameter>val</parameter> can be almost any type.
503 If <varname>env</varname> does not have a &consvar;
504 named <parameter>key</parameter>,
505 then <parameter>key</parameter> is simply
506 stored with a value of <parameter>val</parameter>.
507 Otherwise, <parameter>val</parameter> is
508 combined with the existing value,
509 possibly converting into an appropriate type
510 which can hold the expanded contents.
511 There are a few special cases to be aware of.
512 Normally, when two strings are combined,
513 the result is a new string containing their concatenation
514 (and you are responsible for supplying any needed separation);
515 however, the contents of &cv-link-CPPDEFINES;
516 will be post-processed by adding a prefix and/or suffix
517 to each entry when the command line is produced,
518 so &SCons; keeps them separate -
519 appending a string will result in a separate string entry,
520 not a combined string.
521 For &cv-CPPDEFINES;. as well as
522 &cv-link-LIBS;, and the various <literal>*PATH</literal> variables,
523 &SCons; will amend the variable by supplying the compiler-specific
524 syntax (e.g. prepending a <literal>-D</literal> or <literal>/D</literal>
525 prefix for &cv-CPPDEFINES;), so you should omit this syntax when
526 adding values to these variables.
527 Examples (gcc syntax shown in the expansion of &CPPDEFINES;):
528 </para>
530 <example_commands>
531 env = Environment(CXXFLAGS="-std=c11", CPPDEFINES="RELEASE")
532 print(f"CXXFLAGS = {env['CXXFLAGS']}, CPPDEFINES = {env['CPPDEFINES']}")
533 # notice including a leading space in CXXFLAGS addition
534 env.Append(CXXFLAGS=" -O", CPPDEFINES="EXTRA")
535 print(f"CXXFLAGS = {env['CXXFLAGS']}, CPPDEFINES = {env['CPPDEFINES']}")
536 print("CPPDEFINES will expand to", env.subst('$_CPPDEFFLAGS'))
537 </example_commands>
539 <screen>
540 $ scons -Q
541 CXXFLAGS = -std=c11, CPPDEFINES = RELEASE
542 CXXFLAGS = -std=c11 -O, CPPDEFINES = deque(['RELEASE', 'EXTRA'])
543 CPPDEFINES will expand to -DRELEASE -DEXTRA
544 scons: `.' is up to date.
545 </screen>
547 <para>
548 Because &cv-link-CPPDEFINES; is intended for command-line
549 specification of C/C++ preprocessor macros,
550 additional syntax is accepted when adding to it.
551 The preprocessor accepts arguments to predefine a macro name by itself
552 (<computeroutput>-DFOO</computeroutput> for most compilers,
553 <computeroutput>/DFOO</computeroutput> for Microsoft C++),
554 which gives it an implicit value of <constant>1</constant>,
555 or can be given with a replacement value
556 (<computeroutput>-DBAR=TEXT</computeroutput>).
557 &SCons; follows these rules when adding to &cv-CPPDEFINES;:
558 </para>
559 <itemizedlist>
560 <listitem>
561 <para>A string is split on spaces,
562 giving an easy way to enter multiple macros in one addition.
563 Use an <literal>=</literal> to specify a valued macro.</para>
564 </listitem>
565 <listitem>
566 <para>A tuple is treated as a valued macro.
567 Use the value <constant>None</constant> if the macro should not have a value.
568 It is an error to supply more than two elements in such a tuple.</para>
569 </listitem>
570 <listitem>
571 <para>A list is processed in order,
572 adding each item without further interpretation.
573 In this case, space-separated strings are not split.</para>
574 </listitem>
575 <listitem>
576 <para>A dictionary is processed in order,
577 adding each key-value pair as a valued macro.
578 Use the value <constant>None</constant> if the macro should not have a value.
579 </para>
580 </listitem>
581 </itemizedlist>
583 <para>
584 Examples:
585 </para>
587 <example_commands>
588 env = Environment(CPPDEFINES="FOO")
589 print("CPPDEFINES =", env['CPPDEFINES'])
590 env.Append(CPPDEFINES="BAR=1")
591 print("CPPDEFINES =", env['CPPDEFINES'])
592 env.Append(CPPDEFINES=[("OTHER", 2)])
593 print("CPPDEFINES =", env['CPPDEFINES'])
594 env.Append(CPPDEFINES={"EXTRA": "arg"})
595 print("CPPDEFINES =", env['CPPDEFINES'])
596 print("CPPDEFINES will expand to", env.subst('$_CPPDEFFLAGS'))
597 </example_commands>
599 <screen>
600 $ scons -Q
601 CPPDEFINES = FOO
602 CPPDEFINES = deque(['FOO', 'BAR=1'])
603 CPPDEFINES = deque(['FOO', 'BAR=1', ('OTHER', 2)])
604 CPPDEFINES = deque(['FOO', 'BAR=1', ('OTHER', 2), ('EXTRA', 'arg')])
605 CPPDEFINES will expand to -DFOO -DBAR=1 -DOTHER=2 -DEXTRA=arg
606 scons: `.' is up to date.
607 </screen>
609 <para>
610 Examples of adding multiple macros:
611 </para>
613 <example_commands>
614 env = Environment()
615 env.Append(CPPDEFINES=[("ONE", 1), "TWO", ("THREE", )])
616 print("CPPDEFINES =", env['CPPDEFINES'])
617 env.Append(CPPDEFINES={"FOUR": 4, "FIVE": None})
618 print("CPPDEFINES =", env['CPPDEFINES'])
619 print("CPPDEFINES will expand to", env.subst('$_CPPDEFFLAGS'))
620 </example_commands>
622 <screen>
623 $ scons -Q
624 CPPDEFINES = [('ONE', 1), 'TWO', ('THREE',)]
625 CPPDEFINES = deque([('ONE', 1), 'TWO', ('THREE',), ('FOUR', 4), ('FIVE', None)])
626 CPPDEFINES will expand to -DONE=1 -DTWO -DTHREE -DFOUR=4 -DFIVE
627 scons: `.' is up to date.
628 </screen>
630 <para>
631 <emphasis>Changed in version  4.5</emphasis>:
632 clarified the use of tuples vs. other types,
633 handling is now consistent across the four functions.
634 </para>
636 <example_commands>
637 env = Environment()
638 env.Append(CPPDEFINES=("MACRO1", "MACRO2"))
639 print("CPPDEFINES =", env['CPPDEFINES'])
640 env.Append(CPPDEFINES=[("MACRO3", "MACRO4")])
641 print("CPPDEFINES =", env['CPPDEFINES'])
642 print("CPPDEFINES will expand to", env.subst('$_CPPDEFFLAGS'))
643 </example_commands>
645 <screen>
646 $ scons -Q
647 CPPDEFINES = ('MACRO1', 'MACRO2')
648 CPPDEFINES = deque(['MACRO1', 'MACRO2', ('MACRO3', 'MACRO4')])
649 CPPDEFINES will expand to -DMACRO1 -DMACRO2 -DMACRO3=MACRO4
650 scons: `.' is up to date.
651 </screen>
653 <para>
654 See &cv-link-CPPDEFINES; for more details.
655 </para>
657 <para>
658 Appending a string <parameter>val</parameter>
659 to a dictionary-typed &consvar; enters
660 <parameter>val</parameter> as the key in the dictionary,
661 and <literal>None</literal> as its value.
662 Using a tuple type to supply a key-value pair
663 only works for the special case of &cv-CPPDEFINES;
664 described above.
665 </para>
667 <para>
668 Although most combinations of types work without
669 needing to know the details, some combinations
670 do not make sense and &Python; raises an exception.
671 </para>
673 <para>
674 When using &f-env-Append; to modify &consvars;
675 which are path specifications (conventionally,
676 the names of such end in <literal>PATH</literal>),
677 it is recommended to add the values as a list of strings,
678 even if you are only adding a single string.
679 The same goes for adding library names to &cv-LIBS;.
680 </para>
682 <example_commands>
683 env.Append(CPPPATH=["#/include"])
684 </example_commands>
686 <para>
687 See also &f-link-env-AppendUnique;,
688 &f-link-env-Prepend; and &f-link-env-PrependUnique;.
689 </para>
691 </listitem>
692   </varlistentry>
693   <varlistentry id="f-AppendENVPath">
694     <term><replaceable>env</replaceable>.<methodname>AppendENVPath</methodname>(<parameter>name, newpath, [envname, sep, delete_existing=False]</parameter>)</term>
695     <listitem><para>
696 Append path elements specified by <parameter>newpath</parameter>
697 to the given search path string or list <parameter>name</parameter>
698 in mapping <parameter>envname</parameter> in the &consenv;.
699 Supplying <parameter>envname</parameter> is optional:
700 the default is the execution environment &cv-link-ENV;.
701 Optional <parameter>sep</parameter> is used as the search path separator,
702 the default is the platform's separator (<systemitem>os.pathsep</systemitem>).
703 A path element will only appear once.
704 Any duplicates in <parameter>newpath</parameter> are dropped,
705 keeping the last appearing (to preserve path order).
706 If <parameter>delete_existing</parameter>
707 is <constant>False</constant> (the default)
708 any addition duplicating an existing path element is ignored;
709 if <parameter>delete_existing</parameter>
710 is <constant>True</constant> the existing value will
711 be dropped and the path element will be added at the end.
712 To help maintain uniqueness all paths are normalized (using
713 <systemitem>os.path.normpath</systemitem>
715 <systemitem>os.path.normcase</systemitem>).
716 </para>
718 <para>
719 Example:
720 </para>
722 <example_commands>
723 print('before:', env['ENV']['INCLUDE'])
724 include_path = '/foo/bar:/foo'
725 env.AppendENVPath('INCLUDE', include_path)
726 print('after:', env['ENV']['INCLUDE'])
727 </example_commands>
729 <para>Yields:</para>
730 <screen>
731 before: /foo:/biz
732 after: /biz:/foo/bar:/foo
733 </screen>
735 <para>
736 See also &f-link-env-PrependENVPath;.
737 </para>
739 </listitem>
740   </varlistentry>
741   <varlistentry id="f-AppendUnique">
742     <term><replaceable>env</replaceable>.<methodname>AppendUnique</methodname>(<parameter>key=val, [...], [delete_existing=False]</parameter>)</term>
743     <listitem><para>
744 Append values to &consvars; in the current &consenv;,
745 maintaining uniqueness.
746 Works like &f-link-env-Append;,
747 except that values that would become duplicates
748 are not added.
749 If <parameter>delete_existing</parameter>
750 is set to a true value, then for any duplicate,
751 the existing instance of <parameter>val</parameter> is first removed,
752 then <parameter>val</parameter> is appended,
753 having the effect of moving it to the end.
754 </para>
756 <para>
757 Example:
758 </para>
760 <example_commands>
761 env.AppendUnique(CCFLAGS='-g', FOO=['foo.yyy'])
762 </example_commands>
764 <para>
765 See also &f-link-env-Append;,
766 &f-link-env-Prepend;
767 and &f-link-env-PrependUnique;.
768 </para>
769 </listitem>
770   </varlistentry>
771   <varlistentry id="f-Builder">
772     <term><function>Builder</function>(<parameter>action, [arguments]</parameter>)</term>
773     <term><replaceable>env</replaceable>.<methodname>Builder</methodname>(<parameter>action, [arguments]</parameter>)</term>
774     <listitem><para>
775 Creates a Builder object for
776 the specified
777 <parameter>action</parameter>.
778 See the manpage section "Builder Objects"
779 for a complete explanation of the arguments and behavior.
780 </para>
782 <para>
783 Note that the
784 <function>env.Builder</function>()
785 form of the invocation will expand
786 &consvars; in any arguments strings,
787 including the
788 <parameter>action</parameter>
789 argument,
790 at the time it is called
791 using the &consvars; in the
792 <varname>env</varname>
793 &consenv; through which
794 &f-env-Builder; was called.
796 &f-Builder;
797 form delays all variable expansion
798 until after the Builder object is actually called.
799 </para>
800 </listitem>
801   </varlistentry>
802   <varlistentry id="f-CacheDir">
803     <term><function>CacheDir</function>(<parameter>cache_dir, custom_class=None</parameter>)</term>
804     <term><replaceable>env</replaceable>.<methodname>CacheDir</methodname>(<parameter>cache_dir, custom_class=None</parameter>)</term>
805     <listitem><para>
806 Direct
807 &scons;
808 to maintain a derived-file cache in
809 <parameter>cache_dir</parameter>.
810 The derived files in the cache will be shared
811 among all the builds specifying the same
812 <parameter>cache_dir</parameter>.
813 Specifying a
814 <parameter>cache_dir</parameter>
816 <constant>None</constant>
817 disables derived file caching.
818 </para>
820 <para>
821 Calling the environment method
822 &f-link-env-CacheDir;
823 limits the effect to targets built
824 through the specified &consenv;.
825 Calling the global function
826 &f-link-CacheDir;
827 sets a global default
828 that will be used by all targets built
829 through &consenvs;
830 that do not set up environment-specific
831 caching by calling &f-env-CacheDir;.
832 </para>
834 <para>
835 Caching behavior can be configured by passing a specialized cache
836 class as the optional <parameter>custom_class</parameter> parameter.
837 This class must be a subclass of
838 <classname>SCons.CacheDir.CacheDir</classname>.
839 &SCons; will internally invoke the custom class for performing
840 caching operations.
841 If the parameter is omitted or set to
842 <constant>None</constant>, &SCons; will use the default
843 <classname>SCons.CacheDir.CacheDir</classname> class.
844 </para>
846 <para>
847 When derived-file caching
848 is being used and
849 &scons;
850 finds a derived file that needs to be rebuilt,
851 it will first look in the cache to see if a
852 file with matching &buildsig; exists
853 (indicating the input file(s) and build action(s)
854 were identical to those for the current target),
855 and if so, will retrieve the file from the cache.
856 &scons;
857 will report
858 <computeroutput>Retrieved `file' from cache</computeroutput>
859 instead of the normal build message.
860 If the derived file is not present in the cache,
861 &scons;
862 will build it and
863 then place a copy of the built file in the cache,
864 identified by its &buildsig;, for future use.
865 </para>
867 <para>
869 <computeroutput>Retrieved `file' from cache</computeroutput>
870 messages are useful for human consumption,
871 but less useful when comparing log files between
872 &scons; runs which will show differences that are
873 noisy and not actually significant.
874 To disable,
875 use the <option>--cache-show</option> option.
876 With this option, &scons; changes printing
877 to always show the action that would
878 have been used to build the file without caching.
879 </para>
881 <para>
882 Derived-file caching
883 may be disabled for any invocation
884 of &scons; by giving the
885 <option>--cache-disable</option>
886 command line option;
887 cache updating may be disabled, leaving cache
888 fetching enabled, by giving the
889 <option>--cache-readonly</option> option.
890 </para>
892 <para>
893 If the
894 <option>--cache-force</option>
895 option is used,
896 &scons;
897 will place a copy of
898 <emphasis>all</emphasis>
899 derived files into the cache,
900 even if they already existed
901 and were not built by this invocation.
902 This is useful to populate a cache
903 the first time a
904 <parameter>cache_dir</parameter>
905 is used for a build,
906 or to bring a cache up to date after
907 a build with cache updating disabled
908 (<option>--cache-disable</option>
909 or <option>--cache-readonly</option>)
910 has been done.
911 </para>
913 <para>
915 &f-link-NoCache;
916 method can be used to disable caching of specific files.  This can be
917 useful if inputs and/or outputs of some tool are impossible to
918 predict or prohibitively large.
919 </para>
921 <para>
922 Note that (at this time) &SCons; provides no facilities
923 for managing the derived-file cache. It is up to the developer
924 to arrange for cache pruning, expiry, access control, etc. if needed.
925 </para>
927 </listitem>
928   </varlistentry>
929   <varlistentry id="f-Clean">
930     <term><function>Clean</function>(<parameter>targets, files_or_dirs</parameter>)</term>
931     <term><replaceable>env</replaceable>.<methodname>Clean</methodname>(<parameter>targets, files_or_dirs</parameter>)</term>
932     <listitem><para>
933 This specifies a list of files or directories which should be removed
934 whenever the targets are specified with the
935 <option>-c</option>
936 command line option.
937 The specified targets may be a list
938 or an individual target.
939 Multiple calls to
940 &f-Clean;
941 are legal,
942 and create new targets or add files and directories to the
943 clean list for the specified targets.
944 </para>
946 <para>
947 Multiple files or directories should be specified
948 either as separate arguments to the
949 &f-Clean;
950 method, or as a list.
951 &f-Clean;
952 will also accept the return value of the &consenv;
953 Builder methods.
954 Examples:
955 </para>
957 <para>
958 The related
959 &f-link-NoClean;
960 function overrides calling
961 &f-Clean;
962 for the same target,
963 and any targets passed to both functions will
964 <emphasis>not</emphasis>
965 be removed by the
966 <option>-c</option>
967 option.
968 </para>
970 <para>
971 Examples:
972 </para>
974 <example_commands>
975 Clean('foo', ['bar', 'baz'])
976 Clean('dist', env.Program('hello', 'hello.c'))
977 Clean(['foo', 'bar'], 'something_else_to_clean')
978 </example_commands>
980 <para>
981 In this example,
982 installing the project creates a subdirectory for the documentation.
983 This statement causes the subdirectory to be removed
984 if the project is uninstalled.
985 </para>
986 <example_commands>
987 Clean(docdir, os.path.join(docdir, projectname))
988 </example_commands>
989 </listitem>
990   </varlistentry>
991   <varlistentry id="f-Clone">
992     <term><replaceable>env</replaceable>.<methodname>Clone</methodname>(<parameter>[key=val, ...]</parameter>)</term>
993     <listitem><para>
994 Returns an independent copy of a &consenv;.
995 If there are any unrecognized keyword arguments specified,
996 they are added as &consvars; in the copy,
997 overwriting any existing values
998 for those keywords.
999 See the manpage section "Construction Environments" for more details.
1000 </para>
1002 <para>
1003 Example:
1004 </para>
1006 <example_commands>
1007 env2 = env.Clone()
1008 env3 = env.Clone(CCFLAGS='-g')
1009 </example_commands>
1011 <para>
1012 A list of <parameter>tools</parameter>
1013 and a <parameter>toolpath</parameter> may be specified,
1014 as in the &f-link-Environment; constructor:
1015 </para>
1017 <example_commands>
1018 def MyTool(env):
1019     env['FOO'] = 'bar'
1021 env4 = env.Clone(tools=['msvc', MyTool])
1022 </example_commands>
1024 <para>
1026 <parameter>parse_flags</parameter>
1027 keyword argument is also recognized, to allow merging command-line
1028 style arguments into the appropriate construction
1029 variables (see &f-link-env-MergeFlags;).
1030 </para>
1032 <example_commands>
1033 # create an environment for compiling programs that use wxWidgets
1034 wx_env = env.Clone(parse_flags='!wx-config --cflags --cxxflags')
1035 </example_commands>
1037 <para>
1038 The <parameter>variables</parameter>
1039 keyword argument is also recognized, to allow (re)initializing
1040 &consvars; from a <literal>Variables</literal> object.
1041 </para>
1043 <para>
1044 <emphasis>Changed in version 4.8.0:</emphasis>
1045 the <parameter>variables</parameter> parameter was added.
1046 </para>
1047 </listitem>
1048   </varlistentry>
1049   <varlistentry id="f-Command">
1050     <term><function>Command</function>(<parameter>target, source, action, [key=val, ...]</parameter>)</term>
1051     <term><replaceable>env</replaceable>.<methodname>Command</methodname>(<parameter>target, source, action, [key=val, ...]</parameter>)</term>
1052     <listitem><para>
1053 Creates an anonymous builder and calls it,
1054 thus recording <parameter>action</parameter>
1055 to build <parameter>target</parameter>
1056 from <parameter>source</parameter>
1057 into the dependency tree.
1058 This can be more convenient for a single special-case build
1059 than having to define and add a new named Builder.
1060 </para>
1062 <para>
1064 &Command; function accepts the
1065 <parameter>source_scanner</parameter> and
1066 <parameter>target_scanner</parameter>
1067 keyword arguments which are used to specify
1068 custom scanners for the specified sources or targets.
1069 The value must be a Scanner object.
1070 For example, the global
1071 <literal>DirScanner</literal>
1072 object can be used
1073 if any of the sources will be directories
1074 that must be scanned on-disk for
1075 changes to files that aren't
1076 already specified in other Builder or function calls.
1077 </para>
1079 <para>
1081 &Command; function also accepts the
1082 <parameter>source_factory</parameter> and
1083 <parameter>target_factory</parameter>
1084 keyword arguments which are used to specify
1085 factory functions to create &SCons; Nodes
1086 from any sources or targets specified as strings.
1087 If any sources or targets are already Node objects,
1088 they are not further transformed even if
1089 a factory is specified for them.
1090 The default for each is the &Entry; factory.
1091 </para>
1093 <para>
1094 These four arguments, if given, are used
1095 in the creation of the Builder.
1096 Other Builder-specific keyword arguments
1097 are not recognized as such.
1098 See the manpage section "Builder Objects"
1099 for more information about how these
1100 arguments work in a Builder.
1101 </para>
1103 <para>
1104 Any remaining keyword arguments are passed on to the
1105 generated builder when it is called,
1106 and behave as described in the manpage section "Builder Methods",
1107 in short:
1108 recognized arguments have their specified meanings,
1109 while the rest are used to override
1110 any same-named existing &consvars;
1111 from the &consenv;.
1112 </para>
1114 <para>
1115 <parameter>action</parameter> can be an external command,
1116 specified as a string,
1117 or a callable &Python; object;
1118 see the manpage section "Action Objects"
1119 for more complete information.
1120 Also note that a string specifying an external command
1121 may be preceded by an at-sign
1122 (<literal>@</literal>)
1123 to suppress printing the command in question,
1124 or by a hyphen
1125 (<literal>-</literal>)
1126 to ignore the exit status of the external command.
1127 </para>
1129 <para>
1130 Examples:
1131 </para>
1133 <example_commands>
1134 env.Command(
1135     target='foo.out',
1136     source='foo.in',
1137     action="$FOO_BUILD &lt; $SOURCES &gt; $TARGET"
1140 env.Command(
1141     target='bar.out',
1142     source='bar.in',
1143     action=["rm -f $TARGET", "$BAR_BUILD &lt; $SOURCES &gt; $TARGET"],
1144     ENV={'PATH': '/usr/local/bin/'},
1148 import os
1149 def rename(env, target, source):
1150     os.rename('.tmp', str(target[0]))
1153 env.Command(
1154     target='baz.out',
1155     source='baz.in',
1156     action=["$BAZ_BUILD &lt; $SOURCES &gt; .tmp", rename],
1158 </example_commands>
1160 <para>
1161 Note that the
1162 &Command;
1163 function will usually assume, by default,
1164 that the specified targets and/or sources are Files,
1165 if no other part of the configuration
1166 identifies what type of entries they are.
1167 If necessary, you can explicitly specify
1168 that targets or source nodes should
1169 be treated as directories
1170 by using the
1171 &f-link-Dir;
1173 &f-link-env-Dir;
1174 functions.
1175 </para>
1177 <para>
1178 Examples:
1179 </para>
1181 <example_commands>
1182 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE &gt; $TARGET')
1184 env['DISTDIR'] = 'destination/directory'
1185 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
1186 </example_commands>
1188 <para>
1189 Also note that SCons will usually
1190 automatically create any directory necessary to hold a target file,
1191 so you normally don't need to create directories by hand.
1192 </para>
1193 </listitem>
1194   </varlistentry>
1195   <varlistentry id="f-Configure">
1196     <term><function>Configure</function>(<parameter>env, [custom_tests, conf_dir, log_file, config_h]</parameter>)</term>
1197     <term><replaceable>env</replaceable>.<methodname>Configure</methodname>(<parameter>[custom_tests, conf_dir, log_file, config_h]</parameter>)</term>
1198     <listitem><para>
1199 Creates a &Configure; object for integrated
1200 functionality similar to GNU <command>autoconf</command>.
1201 See the manpage section "Configure Contexts"
1202 for a complete explanation of the arguments and behavior.
1203 </para>
1204 </listitem>
1205   </varlistentry>
1206   <varlistentry id="f-DebugOptions">
1207     <term><function>DebugOptions</function>(<parameter>[json]</parameter>)</term>
1208     <listitem><para>
1209 Allows setting options for SCons debug options. Currently, the only supported value is
1210   <emphasis>json</emphasis> which sets the path to the JSON file created when
1211   <literal>--debug=json</literal> is set.
1212 </para>
1213   <example_commands>
1214 DebugOptions(json='#/build/output/scons_stats.json')
1215 </example_commands>
1216 <para><emphasis>New in version 4.6.0.</emphasis></para>
1217 </listitem>
1218   </varlistentry>
1219   <varlistentry id="f-Decider">
1220     <term><function>Decider</function>(<parameter>function</parameter>)</term>
1221     <term><replaceable>env</replaceable>.<methodname>Decider</methodname>(<parameter>function</parameter>)</term>
1222     <listitem><para>
1223 Specifies that all up-to-date decisions for
1224 targets built through this &consenv;
1225 will be handled by <parameter>function</parameter>.
1226 <parameter>function</parameter> can be the name of
1227 a function or one of the following strings
1228 that specify a predefined decider function:
1229 </para>
1231 <para>
1232 <variablelist>
1233 <varlistentry>
1234 <term><literal>"content"</literal></term>
1235 <listitem>
1236 <para>
1237 Specifies that a target shall be considered out-of-date and rebuilt
1238 if the dependency's content has changed since the last time
1239 the target was built,
1240 as determined by performing a checksum
1241 on the dependency's contents using the selected hash function,
1242 and comparing it to the checksum recorded the
1243 last time the target was built.
1244 <literal>content</literal> is the default decider.
1245 </para>
1246 <para>
1247 <emphasis>Changed in version 4.1:</emphasis>
1248 The decider was renamed to <literal>content</literal>
1249 since the hash function is now selectable.
1250 The former name, <literal>MD5</literal>,
1251 can still be used as a synonym, but is deprecated.
1252 </para>
1253 </listitem>
1254 </varlistentry>
1255 <varlistentry>
1256 <term><literal>"content-timestamp"</literal></term>
1257 <listitem>
1258 <para>
1259 Specifies that a target shall be considered out-of-date and rebuilt
1260 if the dependency's content has changed since the last time
1261 the target was built,
1262 except that dependencies with a timestamp that matches
1263 the last time the target was rebuilt will be
1264 assumed to be up-to-date and
1265 <emphasis>not</emphasis>
1266 rebuilt.
1267 This provides behavior very similar
1268 to the
1269 <literal>content</literal>
1270 behavior of always checksumming file contents,
1271 with an optimization of not checking
1272 the contents of files whose timestamps haven't changed.
1273 The drawback is that SCons will
1274 <emphasis>not</emphasis>
1275 detect if a file's content has changed
1276 but its timestamp is the same,
1277 as might happen in an automated script
1278 that runs a build,
1279 updates a file,
1280 and runs the build again,
1281 all within a single second.
1282 </para>
1283 <para>
1284 <emphasis>Changed in version 4.1:</emphasis>
1285 The decider was renamed to <literal>content-timestamp</literal>
1286 since the hash function is now selectable.
1287 The former name, <literal>MD5-timestamp</literal>,
1288 can still be used as a synonym, but is deprecated.
1289 </para>
1290 </listitem>
1291 </varlistentry>
1292 <varlistentry>
1293 <term><literal>"timestamp-newer"</literal></term>
1294 <listitem>
1295 <para>
1296 Specifies that a target shall be considered out-of-date and rebuilt
1297 if the dependency's timestamp is newer than the target file's timestamp.
1298 This is the behavior of the classic Make utility,
1300 <literal>make</literal>
1301 can be used a synonym for
1302 <literal>timestamp-newer</literal>.
1303 </para>
1304 </listitem>
1305 </varlistentry>
1306 <varlistentry>
1307 <term><literal>"timestamp-match"</literal></term>
1308 <listitem>
1309 <para>
1310 Specifies that a target shall be considered out-of-date and rebuilt
1311 if the dependency's timestamp is different than the
1312 timestamp recorded the last time the target was built.
1313 This provides behavior very similar to the classic Make utility
1314 (in particular, files are not opened up so that their
1315 contents can be checksummed)
1316 except that the target will also be rebuilt if a
1317 dependency file has been restored to a version with an
1318 <emphasis>earlier</emphasis>
1319 timestamp, such as can happen when restoring files from backup archives.
1320 </para>
1321 </listitem>
1322 </varlistentry>
1323 </variablelist>
1324 </para>
1326 <para>
1327 Examples:
1328 </para>
1330 <example_commands>
1331 # Use exact timestamp matches by default.
1332 Decider('timestamp-match')
1334 # Use hash content signatures for any targets built
1335 # with the attached &consenv;.
1336 env.Decider('content')
1337 </example_commands>
1339 <para>
1340 In addition to the above already-available functions, the
1341 <parameter>function</parameter>
1342 argument may be a &Python; function you supply.
1343 Such a function must accept the following four arguments:
1344 </para>
1346 <para>
1347 <variablelist>
1348 <varlistentry>
1349 <term><parameter>dependency</parameter></term>
1350 <listitem>
1351 <para>
1352 The Node (file) which
1353 should cause the
1354 <parameter>target</parameter>
1355 to be rebuilt
1356 if it has "changed" since the last time
1357 <parameter>target</parameter>
1358 was built.
1359 </para>
1360 </listitem>
1361 </varlistentry>
1362 <varlistentry>
1363 <term><parameter>target</parameter></term>
1364 <listitem>
1365 <para>
1366 The Node (file) being built.
1367 In the normal case,
1368 this is what should get rebuilt
1369 if the
1370 <parameter>dependency</parameter>
1371 has "changed."
1372 </para>
1373 </listitem>
1374 </varlistentry>
1375 <varlistentry>
1376 <term><parameter>prev_ni</parameter></term>
1377 <listitem>
1378 <para>
1379 Stored information about the state of the
1380 <parameter>dependency</parameter>
1381 the last time the
1382 <parameter>target</parameter>
1383 was built.
1384 This can be consulted to match various
1385 file characteristics
1386 such as the timestamp,
1387 size, or &contentsig;.
1388 </para>
1389 </listitem>
1390 </varlistentry>
1391     <varlistentry>
1392 <term><parameter>repo_node</parameter></term>
1393 <listitem>
1394 <para>
1395 If set, use this Node instead of the one specified by
1396 <parameter>dependency</parameter>
1397 to determine if the dependency has changed.
1398 This argument is optional so should be written
1399 as a default argument (typically it would be
1400 written as <parameter>repo_node=None</parameter>).
1401 A caller will normally only set this if the
1402 target only exists in a Repository.
1403 </para>
1404 </listitem>
1405 </varlistentry>
1407 </variablelist>
1408 </para>
1410 <para>
1412 <parameter>function</parameter>
1413 should return a value which evaluates
1414 <constant>True</constant>
1415 if the
1416 <parameter>dependency</parameter>
1417 has "changed" since the last time
1419 <parameter>target</parameter>
1420 was built
1421 (indicating that the target
1422 <emphasis>should</emphasis>
1423 be rebuilt),
1424 and a value which evaluates
1425 <constant>False</constant>
1426 otherwise
1427 (indicating that the target should
1428 <emphasis>not</emphasis>
1429 be rebuilt).
1430 Note that the decision can be made
1431 using whatever criteria are appropriate.
1432 Ignoring some or all of the function arguments
1433 is perfectly normal.
1434 </para>
1436 <para>
1437 Example:
1438 </para>
1440 <example_commands>
1441 def my_decider(dependency, target, prev_ni, repo_node=None):
1442     return not os.path.exists(str(target))
1444 env.Decider(my_decider)
1445 </example_commands>
1446 </listitem>
1447   </varlistentry>
1448   <varlistentry id="f-Default">
1449     <term><function>Default</function>(<parameter>target[, ...]</parameter>)</term>
1450     <term><replaceable>env</replaceable>.<methodname>Default</methodname>(<parameter>target[, ...]</parameter>)</term>
1451     <listitem><para>
1452 Specify default targets to the &SCons; target selection mechanism.
1453 Any call to &f-Default; will cause &SCons; to use the
1454 defined default target list instead of
1455 its built-in algorithm for determining default targets
1456 (see the manpage section "Target Selection").
1457 </para>
1459 <para>
1460 <parameter>target</parameter> may be one or more strings,
1461 a list of strings,
1462 a <classname>NodeList</classname> as returned by a Builder,
1463 or <constant>None</constant>.
1464 A string <parameter>target</parameter> may be the name of
1465 a file or directory, or a target previously defined by a call to
1466 &f-link-Alias; (defining the alias later will still create
1467 the alias, but it will not be recognized as a default).
1468 Calls to &f-Default; are additive.
1469 A <parameter>target</parameter> of
1470 <literal>None</literal>
1471 will clear any existing default target list;
1472 subsequent calls to
1473 &f-Default;
1474 will add to the (now empty) default target list
1475 like normal.
1476 </para>
1478 <para>
1479 Both forms of this call affect the
1480 same global list of default targets; the
1481 construction environment method applies
1482 construction variable expansion to the targets.
1483 </para>
1485 <para>
1486 The current list of targets added using
1487 &f-Default; is available in the
1488 &DEFAULT_TARGETS; list (see below).
1489 </para>
1491 <para>
1492 Examples:
1493 </para>
1495 <example_commands>
1496 Default('foo', 'bar', 'baz')
1497 env.Default(['a', 'b', 'c'])
1498 hello = env.Program('hello', 'hello.c')
1499 env.Default(hello)
1500 </example_commands>
1502 </listitem>
1503   </varlistentry>
1504   <varlistentry id="f-DefaultEnvironment">
1505     <term><function>DefaultEnvironment</function>(<parameter>[key=value, ...]</parameter>)</term>
1506     <listitem><para>
1507 Instantiates and returns the global &consenv; object.
1508 The <firstterm>&DefEnv;</firstterm> is used internally by &SCons;
1509 when executing a global function
1510 or the global form of a Builder method
1511 that requires access to a &consenv;.
1512 </para>
1514 <para>
1515 On the first call,
1516 arguments are interpreted as for the &f-link-Environment; function.
1517 The &DefEnv; is a singleton;
1518 subsequent calls to &f-DefaultEnvironment; return
1519 the already-constructed object,
1520 and any keyword arguments are silently ignored.
1521 </para>
1523 <para>
1524 The &DefEnv; can be modified after instantiation,
1525 similar to other &consenvs;,
1526 although some &consenv; methods may be unavailable.
1527 Modifying the &DefEnv; has no effect on any other &consenv;,
1528 either existing or newly constructed.
1529 </para>
1531 <para>
1532 It is not necessary to explicitly call &f-DefaultEnvironment;.
1533 &SCons; instantiates the &defenv; automatically when the
1534 build phase begins, if has not already been done.
1535 However, calling it explicitly provides the opportunity to
1536 affect and examine its contents.
1537 Instantiation occurs even if nothing in the build system
1538 appears to use it, due to internal uses.
1539 </para>
1541 <para>
1542 If the project &SConscript; files do not use global functions or Builders,
1543 a small performance gain may be achieved by calling
1544 &f-DefaultEnvironment; with an empty tools list
1545 (<userinput>DefaultEnvironment(tools=[])</userinput>).
1546 This avoids the tool initialization cost for the &DefEnv;,
1547 which is mainly of interest in the test suite
1548 where &scons; is launched repeatedly in a short time period.
1549 </para>
1550 </listitem>
1551   </varlistentry>
1552   <varlistentry id="f-Depends">
1553     <term><function>Depends</function>(<parameter>target, dependency</parameter>)</term>
1554     <term><replaceable>env</replaceable>.<methodname>Depends</methodname>(<parameter>target, dependency</parameter>)</term>
1555     <listitem><para>
1556 Specifies an explicit dependency;
1558 <parameter>target</parameter>
1559 will be rebuilt
1560 whenever the
1561 <parameter>dependency</parameter>
1562 has changed.
1563 Both the specified
1564 <parameter>target</parameter>
1566 <parameter>dependency</parameter>
1567 can be a string
1568 (usually the path name of a file or directory)
1569 or Node objects,
1570 or a list of strings or Node objects
1571 (such as returned by a Builder call).
1572 This should only be necessary
1573 for cases where the dependency
1574 is not caught by a Scanner
1575 for the file.
1576 </para>
1578 <para>
1579 Example:
1580 </para>
1582 <example_commands>
1583 env.Depends('foo', 'other-input-file-for-foo')
1585 mylib = env.Library('mylib.c')
1586 installed_lib = env.Install('lib', mylib)
1587 bar = env.Program('bar.c')
1589 # Arrange for the library to be copied into the installation
1590 # directory before trying to build the "bar" program.
1591 # (Note that this is for example only.  A "real" library
1592 # dependency would normally be configured through the $LIBS
1593 # and $LIBPATH variables, not using an env.Depends() call.)
1595 env.Depends(bar, installed_lib)
1596 </example_commands>
1597 </listitem>
1598   </varlistentry>
1599   <varlistentry id="f-Detect">
1600     <term><replaceable>env</replaceable>.<methodname>Detect</methodname>(<parameter>progs</parameter>)</term>
1601     <listitem><para>
1602 Find an executable from one or more choices:
1603 <parameter>progs</parameter> may be a string or a list of strings.
1604 Returns the first value from <parameter>progs</parameter>
1605 that was found, or <constant>None</constant>.
1606 Executable is searched by checking the paths in the execution environment
1607 (<varname>env</varname><literal>['ENV']['PATH']</literal>).
1608 On Windows systems, additionally applies the filename suffixes found in
1609 the execution environment
1610 (<varname>env</varname><literal>['ENV']['PATHEXT']</literal>)
1611 but will not include any such extension in the return value.
1612 &f-env-Detect; is a wrapper around &f-link-env-WhereIs;.
1613 </para>
1614 </listitem>
1615   </varlistentry>
1616   <varlistentry id="f-Dictionary">
1617     <term><replaceable>env</replaceable>.<methodname>Dictionary</methodname>(<parameter>[var, ...], [as_dict=]</parameter>)</term>
1618     <listitem><para>
1619 Return an object containing &consvars; from
1620 <parameter>env</parameter>.
1621 If <parameter>var</parameter> is omitted,
1622 all the &consvars; with their values
1623 are returned in a <type>dict</type>.
1624 If <parameter>var</parameter> is specified,
1625 and <parameter>as_dict</parameter> is true,
1626 the specified &consvars; are returned in a <type>dict</type>;
1627 otherwise (the default, for backwards compatibility),
1628 values only are returned,
1629 as a scalar if one <parameter>var</parameter> is given,
1630 or as a list if multiples.
1631 </para>
1633 <para>
1634 Example:
1635 </para>
1637 <example_commands>
1638 cvars = env.Dictionary()
1639 cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
1640 </example_commands>
1642 <note><para>
1643 The object returned by &f-link-env-Dictionary; should be treated
1644 as a read-only view into the &consvars;.
1645 Some &consvars; require special internal handling,
1646 and modifying them through the &f-env-Dictionary; object can bypass
1647 that handling and cause data inconsistencies.
1648 The primary use of &f-env-Dictionary; is for diagnostic purposes -
1649 it is used widely by test cases specifically because
1650 it bypasses the special handling so that behavior
1651 can be verified.
1652 </para></note>
1654 <para>
1655 <emphasis>Changed in NEXT_RELEASE</emphasis>:
1656 <parameter>as_dict</parameter> added.
1657 </para>
1659 </listitem>
1660   </varlistentry>
1661   <varlistentry id="f-Dir">
1662     <term><function>Dir</function>(<parameter>name, [directory]</parameter>)</term>
1663     <term><replaceable>env</replaceable>.<methodname>Dir</methodname>(<parameter>name, [directory]</parameter>)</term>
1664     <listitem><para>
1665 Returns Directory Node(s).
1666 A Directory Node is an object that represents a directory.
1667 <parameter>name</parameter>
1668 can be a relative or absolute path or a list of such paths.
1669 <parameter>directory</parameter>
1670 is an optional directory that will be used as the parent directory.
1671 If no
1672 <parameter>directory</parameter>
1673 is specified, the current script's directory is used as the parent.
1674 </para>
1676 <para>
1678 <parameter>name</parameter>
1679 is a single pathname, the corresponding node is returned.
1681 <parameter>name</parameter>
1682 is a list, SCons returns a list of nodes.
1683 Construction variables are expanded in
1684 <parameter>name</parameter>.
1685 </para>
1687 <para>
1688 Directory Nodes can be used anywhere you
1689 would supply a string as a directory name
1690 to a Builder method or function.
1691 Directory Nodes have attributes and methods
1692 that are useful in many situations;
1693 see manpage section "Filesystem Nodes"
1694 for more information.
1695 </para>
1696 </listitem>
1697   </varlistentry>
1698   <varlistentry id="f-Dump">
1699     <term><replaceable>env</replaceable>.<methodname>Dump</methodname>(<parameter>[var, ...], [format=TYPE]</parameter>)</term>
1700     <listitem><para>
1701 Serialize &consvars; from <parameter>env</parameter> to a string.
1702 If <varname>var</varname> is omitted,
1703 all the &consvars; are serialized.
1704 If one or more <varname>var</varname> values are supplied,
1705 only those variables and their values are serialized.
1706 </para>
1708 <para>
1709 The optional <parameter>format</parameter> string
1710 selects the serialization format:
1711 </para>
1712 <variablelist>
1713 <varlistentry>
1714 <term><literal>pretty</literal></term>
1715 <listitem>
1716 <para>
1717 Returns a pretty-printed representation
1718 of the &consvars; - the result will look like a
1719 &Python; <type>dict</type>
1720 (this is the default).
1721 </para>
1722 </listitem>
1723 </varlistentry>
1724 <varlistentry>
1725 <term><literal>json</literal></term>
1726 <listitem>
1727 <para>
1728 Returns a JSON-formatted representation of the variables.
1729 The variables will be presented as a JSON object literal,
1730 the JSON equivalent of a &Python; <type>dict</type>..
1731 </para>
1732 </listitem>
1733 </varlistentry>
1734 </variablelist>
1736 <para>
1737 <emphasis>Changed in NEXT_RELEASE</emphasis>:
1738 More than one <parameter>key</parameter> can be specified.
1739 The returned string always looks like a <type>dict</type>
1740 (or equivalent in other formats);
1741 previously a single key serialized only the value,
1742 not the key with the value.
1743 </para>
1745 <para>
1746 Examples: this &SConstruct;
1747 </para>
1749 <example_commands>
1750 env = Environment()
1751 print(env.Dump('CCCOM'))
1752 print(env.Dump('CC', 'CCFLAGS', format='json'))
1753 </example_commands>
1755 <para>
1756 will print something like:
1757 </para>
1759 <example_commands>
1760 {'CCCOM': '$CC -o $TARGET -c $CFLAGS $CCFLAGS $_CCCOMCOM $SOURCES'}
1762     "CC": "gcc",
1763     "CCFLAGS": []
1765 </example_commands>
1767 <para>
1768 While this &SConstruct;:
1769 </para>
1771 <example_commands>
1772 env = Environment()
1773 print(env.Dump())
1774 </example_commands>
1776 <para>
1777 will print something like:
1778 </para>
1779 <example_commands>
1780 { 'AR': 'ar',
1781   'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
1782   'ARFLAGS': ['r'],
1783   'AS': 'as',
1784   'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
1785   'ASFLAGS': [],
1786   ...
1787 </example_commands>
1789 </listitem>
1790   </varlistentry>
1791   <varlistentry id="f-EnsurePythonVersion">
1792     <term><function>EnsurePythonVersion</function>(<parameter>major, minor</parameter>)</term>
1793     <listitem><para>
1794 Ensure that the Python version is at least
1795 <varname>major</varname>.<varname>minor</varname>.
1796 This function will
1797 print out an error message and exit SCons with a non-zero exit code if the
1798 actual Python version is not late enough.
1799 </para>
1801 <para>
1802 Example:
1803 </para>
1805 <example_commands>
1806 EnsurePythonVersion(2,2)
1807 </example_commands>
1808 </listitem>
1809   </varlistentry>
1810   <varlistentry id="f-EnsureSConsVersion">
1811     <term><function>EnsureSConsVersion</function>(<parameter>major, minor, [revision]</parameter>)</term>
1812     <listitem><para>
1813 Ensure that the SCons version is at least
1814 <varname>major.minor</varname>,
1816 <varname>major.minor.revision</varname>.
1818 <varname>revision</varname>
1819 is specified.
1820 This function will
1821 print out an error message and exit SCons with a non-zero exit code if the
1822 actual SCons version is not late enough.
1823 </para>
1825 <para>
1826 Examples:
1827 </para>
1829 <example_commands>
1830 EnsureSConsVersion(0,14)
1832 EnsureSConsVersion(0,96,90)
1833 </example_commands>
1834 </listitem>
1835   </varlistentry>
1836   <varlistentry id="f-Environment">
1837     <term><function>Environment</function>(<parameter>[key=value, ...]</parameter>)</term>
1838     <term><replaceable>env</replaceable>.<methodname>Environment</methodname>(<parameter>[key=value, ...]</parameter>)</term>
1839     <listitem><para>
1840 Return a new &consenv;
1841 initialized with the specified
1842 <parameter>key</parameter>=<replaceable>value</replaceable>
1843 pairs.
1844 The keyword arguments
1845 <parameter>parse_flags</parameter>,
1846 <parameter>platform</parameter>,
1847 <parameter>toolpath</parameter>,
1848 <parameter>tools</parameter>
1849 and <parameter>variables</parameter>
1850 are specially recognized and do not lead to
1851 &consvar; creation.
1852 See the manpage section "Construction Environments" for more details.
1853 </para>
1854 </listitem>
1855   </varlistentry>
1856   <varlistentry id="f-Execute">
1857     <term><function>Execute</function>(<parameter>action, [actionargs ...]</parameter>)</term>
1858     <term><replaceable>env</replaceable>.<methodname>Execute</methodname>(<parameter>action, [actionargs ...]</parameter>)</term>
1859     <listitem><para>
1860 Executes an Action.
1861 <parameter>action</parameter>
1862 may be an Action object
1863 or it may be a command-line string,
1864 list of commands,
1865 or executable &Python; function,
1866 each of which will first be converted
1867 into an Action object
1868 and then executed.
1869 Any additional arguments to &f-Execute;
1870 are passed on to the &f-link-Action; factory function
1871 which actually creates the Action object
1872 (see the manpage section <link linkend="action_objects">Action Objects</link>
1873 for a description). Example:
1874 </para>
1876 <example_commands>
1877 Execute(Copy('file.out', 'file.in'))
1878 </example_commands>
1880 <para>&f-Execute; performs its action immediately,
1881 as part of the SConscript-reading phase.
1882 There are no sources or targets declared in an
1883 &f-Execute; call, so any objects it manipulates
1884 will not be tracked as part of the &SCons; dependency graph.
1885 In the example above, neither
1886 <filename>file.out</filename> nor
1887 <filename>file.in</filename> will be tracked objects.
1888 </para>
1890 <para>
1891 &f-Execute; returns the exit value of the command
1892 or return value of the &Python; function.
1893 &scons;
1894 prints an error message if the executed
1895 <parameter>action</parameter>
1896 fails (exits with or returns a non-zero value),
1897 however it does
1898 <emphasis>not</emphasis>,
1899 automatically terminate the build for such a failure.
1900 If you want the build to stop in response to a failed
1901 &f-Execute;
1902 call,
1903 you must explicitly check for a non-zero return value:
1904 </para>
1906 <example_commands>
1907 if Execute("mkdir sub/dir/ectory"):
1908     # The mkdir failed, don't try to build.
1909     Exit(1)
1910 </example_commands>
1911 </listitem>
1912   </varlistentry>
1913   <varlistentry id="f-Exit">
1914     <term><function>Exit</function>(<parameter>[value]</parameter>)</term>
1915     <listitem><para>
1916 This tells
1917 &scons;
1918 to exit immediately
1919 with the specified
1920 <varname>value</varname>.
1921 A default exit value of
1922 <literal>0</literal>
1923 (zero)
1924 is used if no value is specified.
1925 </para>
1926 </listitem>
1927   </varlistentry>
1928   <varlistentry id="f-Export">
1929     <term><function>Export</function>(<parameter>[vars...], [key=value...]</parameter>)</term>
1930     <term><replaceable>env</replaceable>.<methodname>Export</methodname>(<parameter>[vars...], [key=value...]</parameter>)</term>
1931     <listitem><para>
1932 Exports variables for sharing with other SConscript files.
1933 The variables are added to a global collection where
1934 they can be imported by other SConscript files.
1935 <parameter>vars</parameter> may be one or more
1936 strings, or a list of strings. If any string
1937 contains whitespace, it is split automatically
1938 into individual strings. Each string must
1939 match the name of a variable that is in scope
1940 during evaluation of the current SConscript file,
1941 or an exception is raised.
1942 </para>
1944 <para>
1945 A <parameter>vars</parameter> argument
1946 may also be a dictionary or
1947 individual keyword arguments;
1948 in accordance with &Python; syntax rules,
1949 keyword arguments must come after any
1950 non-keyword arguments.
1951 The dictionary/keyword form can be used
1952 to map the local name of a variable to
1953 a different name to be used for imports.
1954 See the Examples for an illustration of the syntax.
1955 </para>
1957 <para>
1958 &f-Export; calls are cumulative. Specifying a previously
1959 exported variable will replace the previous value in the collection.
1960 Both local variables and global variables can be exported.
1961 </para>
1963 <para>
1964 To use an exported variable, an SConscript must
1965 call &f-link-Import; to bring it into its own scope.
1966 Importing creates an additional reference to the object that
1967 was originally exported, so if that object is mutable,
1968 changes made will be visible to other users of that object.
1969 </para>
1971 <para>
1972 Examples:
1973 </para>
1975 <example_commands>
1976 env = Environment()
1977 # Make env available for all SConscript files to Import().
1978 Export("env")
1980 package = 'my_name'
1981 # Make env and package available for all SConscript files:.
1982 Export("env", "package")
1984 # Make env and package available for all SConscript files:
1985 Export(["env", "package"])
1987 # Make env available using the name debug:
1988 Export(debug=env)
1990 # Make env available using the name debug:
1991 Export({"debug": env})
1992 </example_commands>
1994 <para>
1995 Note that the
1996 &f-link-SConscript;
1997 function also supports an &exports;
1998 argument that allows exporting one or more variables
1999 to the SConscript files invoked by that call (only).
2000 See the description of that function for details.
2001 </para>
2002 </listitem>
2003   </varlistentry>
2004   <varlistentry id="f-File">
2005     <term><function>File</function>(<parameter>name, [directory]</parameter>)</term>
2006     <term><replaceable>env</replaceable>.<methodname>File</methodname>(<parameter>name, [directory]</parameter>)</term>
2007     <listitem><para>
2008 Returns File Node(s).
2009 A File Node is an object that represents a file.
2010 <parameter>name</parameter>
2011 can be a relative or absolute path or a list of such paths.
2012 <parameter>directory</parameter>
2013 is an optional directory that will be used as the parent directory.
2014 If no
2015 <parameter>directory</parameter>
2016 is specified, the current script's directory is used as the parent.
2017 </para>
2019 <para>
2021 <parameter>name</parameter>
2022 is a single pathname, the corresponding node is returned.
2024 <parameter>name</parameter>
2025 is a list, SCons returns a list of nodes.
2026 Construction variables are expanded in
2027 <parameter>name</parameter>.
2028 </para>
2030 <para>
2031 File Nodes can be used anywhere you
2032 would supply a string as a file name
2033 to a Builder method or function.
2034 File Nodes have attributes and methods
2035 that are useful in many situations;
2036 see manpage section "Filesystem Nodes"
2037 for more information.
2038 </para>
2039 </listitem>
2040   </varlistentry>
2041   <varlistentry id="f-FindFile">
2042     <term><function>FindFile</function>(<parameter>file, dirs</parameter>)</term>
2043     <term><replaceable>env</replaceable>.<methodname>FindFile</methodname>(<parameter>file, dirs</parameter>)</term>
2044     <listitem><para>
2045 Search for
2046 <parameter>file</parameter>
2047 in the path specified by
2048 <parameter>dirs</parameter>.
2049 <parameter>dirs</parameter>
2050 may be a list of directory names or a single directory name.
2051 In addition to searching for files that exist in the filesystem,
2052 this function also searches for derived files
2053 that have not yet been built.
2054 </para>
2056 <para>
2057 Example:
2058 </para>
2060 <example_commands>
2061 foo = env.FindFile('foo', ['dir1', 'dir2'])
2062 </example_commands>
2063 </listitem>
2064   </varlistentry>
2065   <varlistentry id="f-FindInstalledFiles">
2066     <term><function>FindInstalledFiles</function>()</term>
2067     <term><replaceable>env</replaceable>.<methodname>FindInstalledFiles</methodname>()</term>
2068     <listitem><para>
2069 Returns the list of targets set up by the
2070 &b-link-Install;
2072 &b-link-InstallAs;
2073 builders.
2074 </para>
2076 <para>
2077 This function serves as a convenient method to select the contents of
2078 a binary package.
2079 </para>
2081 <para>
2082 Example:
2083 </para>
2085 <example_commands>
2086 Install('/bin', ['executable_a', 'executable_b'])
2088 # will return the file node list
2089 # ['/bin/executable_a', '/bin/executable_b']
2090 FindInstalledFiles()
2092 Install('/lib', ['some_library'])
2094 # will return the file node list
2095 # ['/bin/executable_a', '/bin/executable_b', '/lib/some_library']
2096 FindInstalledFiles()
2097 </example_commands>
2098 </listitem>
2099   </varlistentry>
2100   <varlistentry id="f-FindPathDirs">
2101     <term><function>FindPathDirs</function>(<parameter>variable</parameter>)</term>
2102     <listitem><para>
2103 Returns a function
2104 (actually a callable Python object)
2105 intended to be used as the
2106 <varname>path_function</varname>
2107 of a Scanner object.
2108 The returned object will look up the specified
2109 <varname>variable</varname>
2110 in a construction environment
2111 and treat the construction variable's value as a list of
2112 directory paths that should be searched
2113 (like
2114 &cv-link-CPPPATH;,
2115 &cv-link-LIBPATH;,
2116 etc.).
2117 </para>
2119 <para>
2120 Note that use of
2121 &f-FindPathDirs;
2122 is generally preferable to
2123 writing your own
2124 <varname>path_function</varname>
2125 for the following reasons:
2126 1) The returned list will contain all appropriate directories
2127 found in source trees
2128 (when
2129 &f-link-VariantDir;
2130 is used)
2131 or in code repositories
2132 (when
2133 &f-Repository;
2134 or the
2135 <option>-Y</option>
2136 option are used).
2137 2) scons will identify expansions of
2138 <varname>variable</varname>
2139 that evaluate to the same list of directories as,
2140 in fact, the same list,
2141 and avoid re-scanning the directories for files,
2142 when possible.
2143 </para>
2145 <para>
2146 Example:
2147 </para>
2149 <example_commands>
2150 def my_scan(node, env, path, arg):
2151     # Code to scan file contents goes here...
2152     return include_files
2154 scanner = Scanner(name = 'myscanner',
2155                   function = my_scan,
2156                   path_function = FindPathDirs('MYPATH'))
2157 </example_commands>
2158 </listitem>
2159   </varlistentry>
2160   <varlistentry id="f-FindSourceFiles">
2161     <term><function>FindSourceFiles</function>(<parameter>node='"."'</parameter>)</term>
2162     <term><replaceable>env</replaceable>.<methodname>FindSourceFiles</methodname>(<parameter>node='"."'</parameter>)</term>
2163     <listitem><para>
2164 Returns the list of nodes which serve as the source of the built files.
2165 It does so by inspecting the dependency tree starting at the optional
2166 argument
2167 <parameter>node</parameter>
2168 which defaults to the '"."'-node. It will then return all leaves of
2169 <parameter>node</parameter>.
2170 These are all children which have no further children.
2171 </para>
2173 <para>
2174 This function is a convenient method to select the contents of a Source
2175 Package.
2176 </para>
2178 <para>
2179 Example:
2180 </para>
2182 <example_commands>
2183 Program('src/main_a.c')
2184 Program('src/main_b.c')
2185 Program('main_c.c')
2187 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
2188 FindSourceFiles()
2190 # returns ['src/main_b.c', 'src/main_a.c' ]
2191 FindSourceFiles('src')
2192 </example_commands>
2194 <para>
2195 As you can see, build support files (&SConstruct; in the above example)
2196 will also be returned by this function.
2197 </para>
2198 </listitem>
2199   </varlistentry>
2200   <varlistentry id="f-Flatten">
2201     <term><function>Flatten</function>(<parameter>sequence</parameter>)</term>
2202     <term><replaceable>env</replaceable>.<methodname>Flatten</methodname>(<parameter>sequence</parameter>)</term>
2203     <listitem><para>
2204 Takes a sequence (that is, a &Python; list or tuple)
2205 that may contain nested sequences
2206 and returns a flattened list containing
2207 all of the individual elements in any sequence.
2208 This can be helpful for collecting
2209 the lists returned by calls to Builders;
2210 other Builders will automatically
2211 flatten lists specified as input,
2212 but direct &Python; manipulation of
2213 these lists does not.
2214 </para>
2216 <para>
2217 Examples:
2218 </para>
2220 <example_commands>
2221 foo = Object('foo.c')
2222 bar = Object('bar.c')
2224 # Because `foo' and `bar' are lists returned by the Object() Builder,
2225 # `objects' will be a list containing nested lists:
2226 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
2228 # Passing such a list to another Builder is all right because
2229 # the Builder will flatten the list automatically:
2230 Program(source = objects)
2232 # If you need to manipulate the list directly using &Python;, you need to
2233 # call Flatten() yourself, or otherwise handle nested lists:
2234 for object in Flatten(objects):
2235     print(str(object))
2236 </example_commands>
2237 </listitem>
2238   </varlistentry>
2239   <varlistentry id="f-GetBuildFailures">
2240     <term><function>GetBuildFailures</function>()</term>
2241     <listitem><para>
2242 Returns a list of exceptions for the
2243 actions that failed while
2244 attempting to build targets.
2245 Each element in the returned list is a
2246 <classname>BuildError</classname>
2247 object
2248 with the following attributes
2249 that record various aspects
2250 of the build failure:
2251 </para>
2253 <para>
2254 <literal>.node</literal>
2255 The node that was being built
2256 when the build failure occurred.
2257 </para>
2259 <para>
2260 <literal>.status</literal>
2261 The numeric exit status
2262 returned by the command or Python function
2263 that failed when trying to build the
2264 specified Node.
2265 </para>
2267 <para>
2268 <literal>.errstr</literal>
2269 The SCons error string
2270 describing the build failure.
2271 (This is often a generic
2272 message like "Error 2"
2273 to indicate that an executed
2274 command exited with a status of 2.)
2275 </para>
2277 <para>
2278 <literal>.filename</literal>
2279 The name of the file or
2280 directory that actually caused the failure.
2281 This may be different from the
2282 <literal>.node</literal>
2283 attribute.
2284 For example,
2285 if an attempt to build a target named
2286 <filename>sub/dir/target</filename>
2287 fails because the
2288 <filename>sub/dir</filename>
2289 directory could not be created,
2290 then the
2291 <literal>.node</literal>
2292 attribute will be
2293 <filename>sub/dir/target</filename>
2294 but the
2295 <literal>.filename</literal>
2296 attribute will be
2297 <filename>sub/dir</filename>.
2298 </para>
2300 <para>
2301 <literal>.executor</literal>
2302 The SCons Executor object
2303 for the target Node
2304 being built.
2305 This can be used to retrieve
2306 the construction environment used
2307 for the failed action.
2308 </para>
2310 <para>
2311 <literal>.action</literal>
2312 The actual SCons Action object that failed.
2313 This will be one specific action
2314 out of the possible list of
2315 actions that would have been
2316 executed to build the target.
2317 </para>
2319 <para>
2320 <literal>.command</literal>
2321 The actual expanded command that was executed and failed,
2322 after expansion of
2323 &cv-link-TARGET;,
2324 &cv-link-SOURCE;,
2325 and other construction variables.
2326 </para>
2328 <para>
2329 Note that the
2330 &f-GetBuildFailures;
2331 function
2332 will always return an empty list
2333 until any build failure has occurred,
2334 which means that
2335 &f-GetBuildFailures;
2336 will always return an empty list
2337 while the
2338 &SConscript;
2339 files are being read.
2340 Its primary intended use is
2341 for functions that will be
2342 executed before SCons exits
2343 by passing them to the
2344 standard Python
2345 <function>atexit.register</function>()
2346 function.
2347 Example:
2348 </para>
2350 <example_commands>
2351 import atexit
2353 def print_build_failures():
2354     from SCons.Script import GetBuildFailures
2355     for bf in GetBuildFailures():
2356         print("%s failed: %s" % (bf.node, bf.errstr))
2358 atexit.register(print_build_failures)
2359 </example_commands>
2360 </listitem>
2361   </varlistentry>
2362   <varlistentry id="f-GetBuildPath">
2363     <term><function>GetBuildPath</function>(<parameter>file, [...]</parameter>)</term>
2364     <term><replaceable>env</replaceable>.<methodname>GetBuildPath</methodname>(<parameter>file, [...]</parameter>)</term>
2365     <listitem><para>
2366 Returns the
2367 &scons;
2368 path name (or names) for the specified
2369 <parameter>file</parameter>
2370 (or files).
2371 The specified
2372 <parameter>file</parameter>
2373 or files
2374 may be
2375 &scons;
2376 Nodes or strings representing path names.
2377 </para>
2378 </listitem>
2379   </varlistentry>
2380   <varlistentry id="f-GetLaunchDir">
2381     <term><function>GetLaunchDir</function>()</term>
2382     <listitem><para>
2383 Returns the absolute path name of the directory from which
2384 &scons;
2385 was initially invoked.
2386 This can be useful when using the
2387 <option>-u</option>,
2388 <option>-U</option>
2390 <option>-D</option>
2391 options, which internally
2392 change to the directory in which the
2393 &SConstruct;
2394 file is found.
2395 </para>
2396 </listitem>
2397   </varlistentry>
2398   <varlistentry id="f-GetOption">
2399     <term><function>GetOption</function>(<parameter>name</parameter>)</term>
2400     <term><replaceable>env</replaceable>.<methodname>GetOption</methodname>(<parameter>name</parameter>)</term>
2401     <listitem><para>
2402 Query the value of settable options which may have been set
2403 on the command line, via option defaults,
2404 or by using the &f-link-SetOption; function.
2405 The value of the option is returned in a type matching how the
2406 option was declared - see the documentation of the
2407 corresponding command line option for information about each specific
2408 option.
2409 </para>
2411 <para>
2412 <parameter>name</parameter> can be an entry from the following table,
2413 which shows the corresponding command line arguments
2414 that could affect the value.
2415 <parameter>name</parameter> can be also be the destination
2416 variable name from a project-specific option added using the
2417 &f-link-AddOption; function, as long as that addition has been
2418 processed prior to the &f-GetOption; call in the &SConscript; files.
2419 </para>
2421 <informaltable rowsep="1" colsep="1" frame="topbot">
2422 <tgroup cols="3">
2423 <thead>
2424 <row>
2425   <entry align="left">Query name</entry>
2426   <entry align="left">Command-line options</entry>
2427   <entry align="left">Notes</entry>
2428 </row>
2429 </thead>
2431 <tbody>
2432 <row>
2433   <entry><varname>cache_debug</varname></entry>
2434   <entry><option>--cache-debug</option></entry>
2435 </row>
2436 <row>
2437   <entry><varname>cache_disable</varname></entry>
2438   <entry>
2439       <option>--cache-disable</option>,
2440       <option>--no-cache</option>
2441   </entry>
2442 </row>
2443 <row>
2444   <entry><varname>cache_force</varname></entry>
2445   <entry>
2446       <option>--cache-force</option>,
2447       <option>--cache-populate</option>
2448   </entry>
2449 </row>
2450 <row>
2451   <entry><varname>cache_readonly</varname></entry>
2452   <entry><option>--cache-readonly</option></entry>
2453 </row>
2454 <row>
2455   <entry><varname>cache_show</varname></entry>
2456   <entry><option>--cache-show</option></entry>
2457 </row>
2458 <row>
2459   <entry><varname>clean</varname></entry>
2460   <entry>
2461       <option>-c</option>,
2462       <option>--clean</option>,
2463       <option>--remove</option>
2464   </entry>
2465 </row>
2466 <row>
2467   <entry><varname>climb_up</varname></entry>
2468   <entry>
2469       <option>-D</option>
2470       <option>-U</option>
2471       <option>-u</option>
2472       <option>--up</option>
2473       <option>--search_up</option>
2474   </entry>
2475 </row>
2476 <row>
2477   <entry><varname>config</varname></entry>
2478   <entry><option>--config</option></entry>
2479 </row>
2480 <row>
2481   <entry><varname>debug</varname></entry>
2482   <entry><option>--debug</option></entry>
2483 </row>
2484 <row>
2485   <entry><varname>directory</varname></entry>
2486   <entry><option>-C</option>, <option>--directory</option></entry>
2487 </row>
2488 <row>
2489   <entry><varname>diskcheck</varname></entry>
2490   <entry><option>--diskcheck</option></entry>
2491 </row>
2492 <row>
2493   <entry><varname>duplicate</varname></entry>
2494   <entry><option>--duplicate</option></entry>
2495 </row>
2496 <row>
2497   <entry><varname>enable_virtualenv</varname></entry>
2498   <entry><option>--enable-virtualenv</option></entry>
2499 </row>
2500 <row>
2501   <entry><varname>experimental</varname></entry>
2502   <entry><option>--experimental</option></entry>
2503   <entry><emphasis>since 4.2</emphasis></entry>
2504 </row>
2505 <row>
2506   <entry><varname>file</varname></entry>
2507   <entry>
2508       <option>-f</option>,
2509       <option>--file</option>,
2510       <option>--makefile</option>,
2511       <option>--sconstruct</option>
2512   </entry>
2513 </row>
2514 <row>
2515   <entry><varname>hash_format</varname></entry>
2516   <entry><option>--hash-format</option></entry>
2517   <entry><emphasis>since 4.2</emphasis></entry>
2518 </row>
2519 <row>
2520   <entry><varname>help</varname></entry>
2521   <entry><option>-h</option>, <option>--help</option></entry>
2522 </row>
2523 <row>
2524   <entry><varname>ignore_errors</varname></entry>
2525   <entry><option>-i</option>, <option>--ignore-errors</option></entry>
2526 </row>
2527 <row>
2528   <entry><varname>ignore_virtualenv</varname></entry>
2529   <entry><option>--ignore-virtualenv</option></entry>
2530 </row>
2531 <row>
2532   <entry><varname>implicit_cache</varname></entry>
2533   <entry><option>--implicit-cache</option></entry>
2534 </row>
2535 <row>
2536   <entry><varname>implicit_deps_changed</varname></entry>
2537   <entry><option>--implicit-deps-changed</option></entry>
2538 </row>
2539 <row>
2540   <entry><varname>implicit_deps_unchanged</varname></entry>
2541   <entry><option>--implicit-deps-unchanged</option></entry>
2542 </row>
2543 <row>
2544   <entry><varname>include_dir</varname></entry>
2545   <entry><option>-I</option>, <option>--include-dir</option></entry>
2546 </row>
2547 <row>
2548   <entry><varname>install_sandbox</varname></entry>
2549   <entry><option>--install-sandbox</option></entry>
2550   <entry>Available only if the &t-link-install; tool has been called</entry>
2551 </row>
2552 <row>
2553   <entry><varname>keep_going</varname></entry>
2554   <entry><option>-k</option>, <option>--keep-going</option></entry>
2555 </row>
2556 <row>
2557   <entry><varname>max_drift</varname></entry>
2558   <entry><option>--max-drift</option></entry>
2559 </row>
2560 <row>
2561   <entry><varname>md5_chunksize</varname></entry>
2562   <entry>
2563       <option>--hash-chunksize</option>,
2564       <option>--md5-chunksize</option>
2565   </entry>
2566   <entry><emphasis><option>--hash-chunksize</option> since 4.2</emphasis></entry>
2567 </row>
2568 <row>
2569   <entry><varname>no_exec</varname></entry>
2570   <entry>
2571       <option>-n</option>,
2572       <option>--no-exec</option>,
2573       <option>--just-print</option>,
2574       <option>--dry-run</option>,
2575       <option>--recon</option>
2576   </entry>
2577 </row>
2578 <row>
2579   <entry><varname>no_progress</varname></entry>
2580   <entry><option>-Q</option></entry>
2581 </row>
2582 <row>
2583   <entry><varname>num_jobs</varname></entry>
2584   <entry><option>-j</option>, <option>--jobs</option></entry>
2585 </row>
2586 <row>
2587   <entry><varname>package_type</varname></entry>
2588   <entry><option>--package-type</option></entry>
2589   <entry>Available only if the &t-link-packaging; tool has been called</entry>
2590 </row>
2591 <row>
2592   <entry><varname>profile_file</varname></entry>
2593   <entry><option>--profile</option></entry>
2594 </row>
2595 <row>
2596   <entry><varname>question</varname></entry>
2597   <entry><option>-q</option>, <option>--question</option></entry>
2598 </row>
2599 <row>
2600   <entry><varname>random</varname></entry>
2601   <entry><option>--random</option></entry>
2602 </row>
2603 <row>
2604   <entry><varname>repository</varname></entry>
2605   <entry>
2606       <option>-Y</option>,
2607       <option>--repository</option>,
2608       <option>--srcdir</option>
2609   </entry>
2610 </row>
2611 <row>
2612   <entry><varname>silent</varname></entry>
2613   <entry>
2614       <option>-s</option>,
2615       <option>--silent</option>,
2616       <option>--quiet</option>
2617   </entry>
2618 </row>
2619 <row>
2620   <entry><varname>site_dir</varname></entry>
2621   <entry><option>--site-dir</option>, <option>--no-site-dir</option></entry>
2622 </row>
2623 <row>
2624   <entry><varname>stack_size</varname></entry>
2625   <entry><option>--stack-size</option></entry>
2626 </row>
2627 <row>
2628   <entry><varname>taskmastertrace_file</varname></entry>
2629   <entry><option>--taskmastertrace</option></entry>
2630 </row>
2631 <row>
2632   <entry><varname>tree_printers</varname></entry>
2633   <entry><option>--tree</option></entry>
2634 </row>
2635 <row>
2636   <entry><varname>warn</varname></entry>
2637   <entry><option>--warn</option>, <option>--warning</option></entry>
2638 </row>
2640 </tbody>
2641 </tgroup>
2642 </informaltable>
2643 </listitem>
2644   </varlistentry>
2645   <varlistentry id="f-GetSConsVersion">
2646     <term><function>GetSConsVersion</function>()</term>
2647     <listitem><para>
2648 Returns the current SCons version in the form of a Tuple[int, int, int],
2649 representing the major, minor, and revision values respectively.
2650 <emphasis>Added in 4.8.0</emphasis>.
2651 </para>
2652 </listitem>
2653   </varlistentry>
2654   <varlistentry id="f-Glob">
2655     <term><function>Glob</function>(<parameter>pattern, [ondisk=True, source=False, strings=False, exclude=None]</parameter>)</term>
2656     <term><replaceable>env</replaceable>.<methodname>Glob</methodname>(<parameter>pattern, [ondisk=True, source=False, strings=False, exclude=None]</parameter>)</term>
2657     <listitem><para>
2658 Returns a possibly empty list of Nodes (or strings) that match
2659 pathname specification <parameter>pattern</parameter>.
2660 <parameter>pattern</parameter> can be absolute,
2661 top-relative,
2662 or (most commonly) relative to the directory of the current
2663 &SConscript; file.
2664 &f-Glob; matches both files stored on disk and Nodes
2665 which &SCons; already knows about, even if any corresponding
2666 file is not currently stored on disk.
2667 The environment method form (&f-env-Glob;)
2668 performs string substitution on
2669 <parameter>pattern</parameter>
2670 and returns whatever matches the resulting expanded pattern.
2671 The results are sorted, unlike for the similar &Python;
2672 <systemitem>glob.glob</systemitem> function,
2673 to ensure build order will be stable.
2674 </para>
2676 <para>
2677 <parameter>pattern</parameter>
2678 can contain POSIX-style shell metacharacters for matching:
2679 </para>
2681 <informaltable rowsep="1" colsep="1" frame="topbot">
2682 <tgroup cols="2">
2683 <thead>
2684   <row>
2685     <entry>Pattern</entry>
2686     <entry>Meaning</entry>
2687   </row>
2688 </thead>
2689 <tbody>
2690   <row>
2691     <entry><literal>*</literal></entry>
2692     <entry>matches everything</entry>
2693   </row>
2694   <row>
2695       <entry><literal>?</literal></entry>
2696       <entry>matches any single character</entry>
2697   </row>
2698   <row>
2699       <entry><literal>[seq]</literal></entry>
2700       <entry>matches any character in <emphasis>seq</emphasis>
2701       (can be a list or a range).</entry>
2702   </row>
2703   <row>
2704       <entry><literal>[!seq]</literal></entry>
2705       <entry>matches any character not in <emphasis>seq</emphasis></entry>
2706   </row>
2707 </tbody>
2708 </tgroup>
2709 </informaltable>
2711 <para>
2712 For a literal match, wrap the metacharacter in brackets to
2713 escape the normal behavior.
2714 For example, <literal>'[?]'</literal> matches the character
2715 <literal>'?'</literal>.
2716 </para>
2718 <para>
2719 Filenames starting with a dot are specially handled -
2720 they can only be matched by patterns that start with a dot
2721 (or have a dot immediately following a pathname separator
2722 character, or slash), they are not not matched by the metacharacters.
2723 Metacharacter matches also do not span directory separators.
2724 </para>
2726 <para>
2727 &f-Glob;
2728 understands repositories
2729 (see the
2730 &f-link-Repository;
2731 function)
2732 and source directories
2733 (see the
2734 &f-link-VariantDir;
2735 function)
2736 and returns a Node (or string, if so configured) match
2737 in the local (SConscript) directory
2738 if a matching Node is found
2739 anywhere in a corresponding
2740 repository or source directory.
2741 </para>
2743 <para>
2744 If the optional
2745 <parameter>ondisk</parameter>
2746 argument evaluates false,
2747 the search for matches on disk is disabled,
2748 and only matches from
2749 already-configured File or Dir Nodes are returned.
2750 The default is to return Nodes for
2751 matches on disk as well.
2752 </para>
2754 <para>
2755 If the optional
2756 <parameter>source</parameter>
2757 argument evaluates true,
2758 and the local directory is a variant directory,
2759 then &f-Glob; returns Nodes from
2760 the corresponding source directory,
2761 rather than the local directory.
2762 <!-- XXX what about generated files that don't exist in src but will be sources? -->
2763 </para>
2765 <para>
2766 If the optional
2767 <parameter>strings</parameter>
2768 argument evaluates true,
2769 &f-Glob;
2770 returns matches as strings, rather than Nodes.
2771 The returned strings will be relative to
2772 the local (SConscript) directory.
2773 (Note that while this may make it easier to perform
2774 arbitrary manipulation of file names,
2775 it loses the context &SCons; would have in the Node,
2776 so if the returned strings are
2777 passed to a different
2778 &SConscript;
2779 file,
2780 any Node translation there will be relative
2781 to that
2782 &SConscript;
2783 directory,
2784 not to the original
2785 &SConscript;
2786 directory.)
2787 </para>
2789 <para>
2790 The optional
2791 <parameter>exclude</parameter>
2792 argument may be set to a pattern or a list of patterns
2793 describing files or directories
2794 to filter out of the match list.
2795 Elements matching a least one specified pattern will be excluded.
2796 These patterns use the same syntax as for
2797 <parameter>pattern</parameter>.
2798 </para>
2800 <para>
2801 Examples:
2802 </para>
2804 <example_commands>
2805 Program("foo", Glob("*.c"))
2806 Zip("/tmp/everything", Glob(".??*") + Glob("*"))
2807 sources = Glob("*.cpp", exclude=["os_*_specific_*.cpp"]) \
2808     + Glob("os_%s_specific_*.cpp" % currentOS)
2809 </example_commands>
2811 </listitem>
2812   </varlistentry>
2813   <varlistentry id="f-Help">
2814     <term><function>Help</function>(<parameter>text, append=False, local_only=False</parameter>)</term>
2815     <term><replaceable>env</replaceable>.<methodname>Help</methodname>(<parameter>text, append=False, local_only=False</parameter>)</term>
2816     <listitem><para>
2817 Adds <parameter>text</parameter> to the help message shown when
2818 &scons; is called with the
2819 <option>-h</option> or <option>--help</option>
2820 argument.
2821 </para>
2822 <para>
2823 On the first call to &f-Help;,
2824 if <parameter>append</parameter> is <constant>False</constant>
2825 (the default), any existing help text is discarded.
2826 The default help text is the help for the &scons;
2827 command itself plus help collected from any
2828 project-local &f-link-AddOption; calls.
2829 This is the help printed if &f-Help; has never been called.
2830 If <parameter>append</parameter> is <constant>True</constant>,
2831 <parameter>text</parameter> is appended to
2832 the existing help text.
2833 If <parameter>local_only</parameter> is also <constant>True</constant>
2834 (the default is <constant>False</constant>),
2835 the project-local help from &f-AddOption; calls is preserved
2836 in the help message but the &scons; command help is not.
2837 </para>
2838 <para>
2839 Subsequent calls to
2840 &f-Help; ignore the keyword arguments
2841 <parameter>append</parameter> and
2842 <parameter>local_only</parameter>
2843 and always append to the existing help text.
2844 </para>
2845 <para>
2846 <emphasis>Changed in 4.6.0</emphasis>: added <parameter>local_only</parameter>.
2847 </para>
2849 </listitem>
2850   </varlistentry>
2851   <varlistentry id="f-Ignore">
2852     <term><function>Ignore</function>(<parameter>target, dependency</parameter>)</term>
2853     <term><replaceable>env</replaceable>.<methodname>Ignore</methodname>(<parameter>target, dependency</parameter>)</term>
2854     <listitem><para>
2855 Ignores <parameter>dependency</parameter>
2856 when deciding if
2857 <parameter>target</parameter> needs to be rebuilt.
2858 <parameter>target</parameter> and
2859 <parameter>dependency</parameter>
2860 can each be a single filename or Node
2861 or a list of filenames or Nodes.
2862 </para>
2864 <para>
2865 &f-Ignore; can also be used to
2866 remove a target from the default build
2867 by specifying the directory the target will be built in as
2868 <parameter>target</parameter>
2869 and the file you want to skip selecting for building as
2870 <parameter>dependency</parameter>.
2871 Note that this only removes the target from
2872 the default target selection algorithm:
2873 if it is a dependency of another object being
2874 built &SCons; still builds it normally.
2875 See the third and forth examples below.
2876 </para>
2878 <para>
2879 Examples:
2880 </para>
2882 <example_commands>
2883 env.Ignore('foo', 'foo.c')
2884 env.Ignore('bar', ['bar1.h', 'bar2.h'])
2885 env.Ignore('.', 'foobar.obj')
2886 env.Ignore('bar', 'bar/foobar.obj')
2887 </example_commands>
2888 </listitem>
2889   </varlistentry>
2890   <varlistentry id="f-Import">
2891     <term><function>Import</function>(<parameter>vars...</parameter>)</term>
2892     <term><replaceable>env</replaceable>.<methodname>Import</methodname>(<parameter>vars...</parameter>)</term>
2893     <listitem><para>
2894 Imports variables into the scope of the current SConscript file.
2895 <parameter>vars</parameter>
2896 must be strings representing names of variables
2897 which have been previously exported either by the
2898 &f-link-Export; function or by the
2899 &exports; argument to the
2900 &f-link-SConscript; function.
2901 Variables exported by the
2902 &f-SConscript; call
2903 take precedence.
2904 Multiple variable names can be passed to
2905 &f-Import;
2906 as separate arguments, as a list of strings,
2907 or as words in a space-separated string.
2908 The wildcard <literal>"*"</literal> can be used to import all
2909 available variables.
2910 </para>
2912 <para>
2913 If the imported variable is mutable,
2914 changes made locally will be reflected in the object the
2915 variable is bound to. This allows subsidiary SConscript files
2916 to contribute to building up, for example, a &consenv;.
2917 </para>
2919 <para>
2920 Examples:
2921 </para>
2923 <example_commands>
2924 Import("env")
2925 Import("env", "variable")
2926 Import(["env", "variable"])
2927 Import("*")
2928 </example_commands>
2929 </listitem>
2930   </varlistentry>
2931   <varlistentry id="f-Literal">
2932     <term><function>Literal</function>(<parameter>string</parameter>)</term>
2933     <term><replaceable>env</replaceable>.<methodname>Literal</methodname>(<parameter>string</parameter>)</term>
2934     <listitem><para>
2935 The specified
2936 <parameter>string</parameter>
2937 will be preserved as-is
2938 and not have &consvars; expanded.
2939 </para>
2940 </listitem>
2941   </varlistentry>
2942   <varlistentry id="f-Local">
2943     <term><function>Local</function>(<parameter>targets</parameter>)</term>
2944     <term><replaceable>env</replaceable>.<methodname>Local</methodname>(<parameter>targets</parameter>)</term>
2945     <listitem><para>
2946 The specified
2947 <parameter>targets</parameter>
2948 will have copies made in the local tree,
2949 even if an already up-to-date copy
2950 exists in a repository.
2951 Returns a list of the target Node or Nodes.
2952 </para>
2953 </listitem>
2954   </varlistentry>
2955   <varlistentry id="f-MergeFlags">
2956     <term><replaceable>env</replaceable>.<methodname>MergeFlags</methodname>(<parameter>arg, [unique]</parameter>)</term>
2957     <listitem><para>
2958 Merges values from
2959 <parameter>arg</parameter>
2960 into &consvars; in <parameter>env</parameter>.
2961 If <parameter>arg</parameter> is a dictionary,
2962 each key-value pair represents a
2963 &consvar; name and the corresponding flags to merge.
2964 If <parameter>arg</parameter>
2965 is not a dictionary,
2966 &MergeFlags; attempts to convert it to one
2967 before the values are merged.
2968 &f-link-env-ParseFlags; is used for this,
2969 so values to be converted are subject to the
2970 same limitations:
2971 &ParseFlags; has knowledge of which &consvars; certain
2972 flags should go to, but not all;
2973 and only for GCC and compatible compiler chains.
2974 <parameter>arg</parameter>
2975 must be a single object,
2976 so to pass multiple strings,
2977 enclose them in a list.
2978 </para>
2980 <para>
2981 If <literal>unique</literal> is true (the default),
2982 duplicate values are not retained.
2983 In case of duplication,
2984 any &consvar; names that end in
2985 <literal>PATH</literal>
2986 keep the left-most value so the
2987 path search order is not altered.
2988 All other &consvars; keep
2989 the right-most value.
2990 If <literal>unique</literal> is false,
2991 values are appended even if they are duplicates.
2992 </para>
2994 <para>
2995 Examples:
2996 </para>
2998 <example_commands>
2999 # Add an optimization flag to $CCFLAGS.
3000 env.MergeFlags({'CCFLAGS': '-O3'})
3002 # Combine the flags returned from running pkg-config with an optimization
3003 # flag and merge the result into the construction variables.
3004 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
3006 # Combine an optimization flag with the flags returned from running pkg-config
3007 # for two distinct packages and merge into the construction variables.
3008 env.MergeFlags(
3009     [
3010         '-O3',
3011         '!pkg-config gtk+-2.0 --cflags --libs',
3012         '!pkg-config libpng12 --cflags --libs',
3013     ]
3015 </example_commands>
3016 </listitem>
3017   </varlistentry>
3018   <varlistentry id="f-NoCache">
3019     <term><function>NoCache</function>(<parameter>target, ...</parameter>)</term>
3020     <term><replaceable>env</replaceable>.<methodname>NoCache</methodname>(<parameter>target, ...</parameter>)</term>
3021     <listitem><para>
3022 Specifies a list of files which should
3023 <emphasis>not</emphasis>
3024 be cached whenever the
3025 &f-link-CacheDir;
3026 method has been activated.
3027 The specified targets may be a list
3028 or an individual target.
3029 </para>
3031 <para>
3032 Multiple files should be specified
3033 either as separate arguments to the
3034 &f-NoCache;
3035 method, or as a list.
3036 &f-NoCache;
3037 will also accept the return value of any of the &consenv;
3038 Builder methods.
3039 </para>
3041 <para>
3042 Calling
3043 &f-NoCache;
3044 on directories and other non-File Node types has no effect because
3045 only File Nodes are cached.
3046 </para>
3048 <para>
3049 Examples:
3050 </para>
3052 <example_commands>
3053 NoCache('foo.elf')
3054 NoCache(env.Program('hello', 'hello.c'))
3055 </example_commands>
3056 </listitem>
3057   </varlistentry>
3058   <varlistentry id="f-NoClean">
3059     <term><function>NoClean</function>(<parameter>target, ...</parameter>)</term>
3060     <term><replaceable>env</replaceable>.<methodname>NoClean</methodname>(<parameter>target, ...</parameter>)</term>
3061     <listitem><para>
3062 Specifies a list of files or directories which should
3063 <emphasis>not</emphasis>
3064 be removed whenever the targets (or their dependencies)
3065 are specified with the
3066 <option>-c</option>
3067 command line option.
3068 The specified targets may be a list
3069 or an individual target.
3070 Multiple calls to
3071 &f-NoClean;
3072 are legal,
3073 and prevent each specified target
3074 from being removed by calls to the
3075 <option>-c</option>
3076 option.
3077 </para>
3079 <para>
3080 Multiple files or directories should be specified
3081 either as separate arguments to the
3082 &f-NoClean;
3083 method, or as a list.
3084 &f-NoClean;
3085 will also accept the return value of any of the &consenv;
3086 Builder methods.
3087 </para>
3089 <para>
3090 Calling
3091 &f-NoClean;
3092 for a target overrides calling
3093 &f-link-Clean;
3094 for the same target,
3095 and any targets passed to both functions will
3096 <emphasis>not</emphasis>
3097 be removed by the
3098 <option>-c</option>
3099 option.
3100 </para>
3102 <para>
3103 Examples:
3104 </para>
3106 <example_commands>
3107 NoClean('foo.elf')
3108 NoClean(env.Program('hello', 'hello.c'))
3109 </example_commands>
3110 </listitem>
3111   </varlistentry>
3112   <varlistentry id="f-ParseConfig">
3113     <term><replaceable>env</replaceable>.<methodname>ParseConfig</methodname>(<parameter>command, [function, unique]</parameter>)</term>
3114     <listitem><para>
3115 Updates the current &consenv; with the values extracted
3116 from the output of running external <parameter>command</parameter>,
3117 by passing it to a helper <parameter>function</parameter>.
3118 <parameter>command</parameter> may be a string
3119 or a list of strings representing the command and
3120 its arguments.
3121 If <parameter>function</parameter>
3122 is omitted or <constant>None</constant>,
3123 &f-link-env-MergeFlags; is used.
3124 By default,
3125 duplicate values are not
3126 added to any &consvars;;
3127 you can specify
3128 <parameter>unique=False</parameter>
3129 to allow duplicate values to be added.
3130 </para>
3132 <para>
3133 <parameter>command</parameter> is executed using the
3134 SCons execution environment (that is, the &consvar;
3135 &cv-link-ENV; in the current &consenv;).
3136 If <parameter>command</parameter> needs additional information
3137 to operate properly, that needs to be set in the execution environment.
3138 For example, <command>pkg-config</command>
3139 may need a custom value set in the <envar>PKG_CONFIG_PATH</envar>
3140 environment variable.
3141 </para>
3143 <para>
3144 &f-env-MergeFlags; needs to understand
3145 the output produced by <parameter>command</parameter>
3146 in order to distribute it to appropriate &consvars;.
3147 &f-env-MergeFlags; uses a separate function to
3148 do that processing -
3149 see &f-link-env-ParseFlags; for the details, including
3150 a table of options and corresponding &consvars;.
3151 To provide alternative processing of the output of
3152 <parameter>command</parameter>,
3153 you can supply a custom
3154 <parameter>function</parameter>,
3155 which must accept three arguments:
3156 the &consenv; to modify,
3157 a string argument containing the output from running
3158 <parameter>command</parameter>,
3159 and the optional
3160 <parameter>unique</parameter> flag.
3161 </para>
3162 </listitem>
3163   </varlistentry>
3164   <varlistentry id="f-ParseDepends">
3165     <term><function>ParseDepends</function>(<parameter>filename, [must_exist, only_one]</parameter>)</term>
3166     <term><replaceable>env</replaceable>.<methodname>ParseDepends</methodname>(<parameter>filename, [must_exist, only_one]</parameter>)</term>
3167     <listitem><para>
3168 Parses the contents of <parameter>filename</parameter>
3169 as a list of dependencies in the style of
3170 &Make;
3172 <application>mkdep</application>,
3173 and explicitly establishes all of the listed dependencies.
3174 </para>
3176 <para>
3177 By default,
3178 it is not an error
3179 if <parameter>filename</parameter>
3180 does not exist.
3181 The optional
3182 <parameter>must_exist</parameter>
3183 argument may be set to <constant>True</constant>
3184 to have &SCons;
3185 raise an exception if the file does not exist,
3186 or is otherwise inaccessible.
3187 </para>
3189 <para>
3190 The optional
3191 <parameter>only_one</parameter>
3192 argument may be set to <constant>True</constant>
3193 to have &SCons; raise an exception
3194 if the file contains dependency
3195 information for more than one target.
3196 This can provide a small sanity check
3197 for files intended to be generated
3198 by, for example, the
3199 <literal>gcc -M</literal>
3200 flag,
3201 which should typically only
3202 write dependency information for
3203 one output file into a corresponding
3204 <filename>.d</filename>
3205 file.
3206 </para>
3208 <para>
3209 <parameter>filename</parameter>
3210 and all of the files listed therein
3211 will be interpreted relative to
3212 the directory of the
3213 &SConscript;
3214 file which calls the
3215 &f-ParseDepends;
3216 function.
3217 </para>
3218 </listitem>
3219   </varlistentry>
3220   <varlistentry id="f-ParseFlags">
3221     <term><replaceable>env</replaceable>.<methodname>ParseFlags</methodname>(<parameter>flags, ...</parameter>)</term>
3222     <listitem><para>
3223 Parses one or more strings containing
3224 typical command-line flags for GCC-style tool chains
3225 and returns a dictionary with the flag values
3226 separated into the appropriate SCons &consvars;.
3227 Intended as a companion to the
3228 &f-link-env-MergeFlags;
3229 method, but allows for the values in the returned dictionary
3230 to be modified, if necessary,
3231 before merging them into the &consenv;.
3232 (Note that
3233 &f-env-MergeFlags;
3234 will call this method if its argument is not a dictionary,
3235 so it is usually not necessary to call
3236 &f-env-ParseFlags;
3237 directly unless you want to manipulate the values.)
3238 </para>
3240 <para>
3241 If the first character in any string is
3242 an exclamation mark (<literal>!</literal>),
3243 the rest of the string is executed as a command,
3244 and the output from the command is
3245 parsed as GCC tool chain command-line flags
3246 and added to the resulting dictionary.
3247 This can be used to call a <filename>*-config</filename>
3248 command typical of the POSIX programming environment
3249 (for example,
3250 <command>pkg-config</command>).
3251 Note that such a command is executed using the
3252 SCons execution environment;
3253 if the command needs additional information,
3254 that information needs to be explicitly provided.
3255 See &f-link-ParseConfig; for more details.
3256 </para>
3258 <para>
3259 Flag values are translated according to the prefix found,
3260 and added to the following &consvars;:
3261 </para>
3263 <example_commands>
3264 -arch                   CCFLAGS, LINKFLAGS
3265 -D                      CPPDEFINES
3266 -framework              FRAMEWORKS
3267 -frameworkdir=          FRAMEWORKPATH
3268 -fmerge-all-constants   CCFLAGS, LINKFLAGS
3269 -fopenmp                CCFLAGS, LINKFLAGS
3270 -fsanitize              CCFLAGS, LINKFLAGS
3271 -include                CCFLAGS
3272 -imacros                CCFLAGS
3273 -isysroot               CCFLAGS, LINKFLAGS
3274 -isystem                CCFLAGS
3275 -iquote                 CCFLAGS
3276 -idirafter              CCFLAGS
3277 -I                      CPPPATH
3278 -l                      LIBS
3279 -L                      LIBPATH
3280 -mno-cygwin             CCFLAGS, LINKFLAGS
3281 -mwindows               LINKFLAGS
3282 -openmp                 CCFLAGS, LINKFLAGS
3283 -pthread                CCFLAGS, LINKFLAGS
3284 -std=                   CFLAGS
3285 -stdlib=                CXXFLAGS
3286 -Wa,                    ASFLAGS, CCFLAGS
3287 -Wl,-rpath=             RPATH
3288 -Wl,-R,                 RPATH
3289 -Wl,-R                  RPATH
3290 -Wl,                    LINKFLAGS
3291 -Wp,                    CPPFLAGS
3292 -                       CCFLAGS
3293 +                       CCFLAGS, LINKFLAGS
3294 </example_commands>
3296 <para>
3297 Any other strings not associated with options
3298 are assumed to be the names of libraries
3299 and added to the
3300 &cv-LIBS; &consvar;.
3301 </para>
3303 <para>
3304 Examples (all of which produce the same result):
3305 </para>
3307 <example_commands>
3308 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
3309 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
3310 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
3311 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
3312 </example_commands>
3313 </listitem>
3314   </varlistentry>
3315   <varlistentry id="f-Platform">
3316     <term><function>Platform</function>(<parameter>plat</parameter>)</term>
3317     <term><replaceable>env</replaceable>.<methodname>Platform</methodname>(<parameter>plat</parameter>)</term>
3318     <listitem><para>
3319 When called as a global function,
3320 returns a callable platform object
3321 selected by <parameter>plat</parameter>
3322 (defaults to the detected platform for the
3323 current system)
3324 that can be used to initialize
3325 a &consenv; by passing it as the
3326 <parameter>platform</parameter> keyword argument to the
3327 &f-link-Environment; function.
3328 </para>
3330 <para>
3331 Example:
3332 </para>
3334 <example_commands>
3335 env = Environment(platform=Platform('win32'))
3336 </example_commands>
3338 <para>
3339 When called as a method of an environment,
3340 calls the platform object indicated by
3341 <parameter>plat</parameter>
3342 to update that environment.
3343 </para>
3345 <example_commands>
3346 env.Platform('posix')
3347 </example_commands>
3349 <para>
3350 See the manpage section "Construction Environments" for more details.
3351 </para>
3352 </listitem>
3353   </varlistentry>
3354   <varlistentry id="f-Precious">
3355     <term><function>Precious</function>(<parameter>target, ...</parameter>)</term>
3356     <term><replaceable>env</replaceable>.<methodname>Precious</methodname>(<parameter>target, ...</parameter>)</term>
3357     <listitem><para>
3358 Marks <varname>target</varname> as precious so it is not
3359 deleted before it is rebuilt.
3360 Normally &SCons; deletes a target before building it.
3361 Multiple targets can be passed in a single call,
3362 and may be strings and/or nodes.
3363 Returns a list of the affected target nodes.
3364 </para>
3365 </listitem>
3366   </varlistentry>
3367   <varlistentry id="f-Prepend">
3368     <term><replaceable>env</replaceable>.<methodname>Prepend</methodname>(<parameter>key=val, [...]</parameter>)</term>
3369     <listitem><para>
3370 Prepend values to &consvars; in the current &consenv;,
3371 works like &f-link-env-Append; (see for details),
3372 except that values are added to the front,
3373 rather than the end, of any existing value of the &consvar;
3374 </para>
3376 <para>
3377 Example:
3378 </para>
3380 <example_commands>
3381 env.Prepend(CCFLAGS='-g ', FOO=['foo.yyy'])
3382 </example_commands>
3384 <para>
3385 See also &f-link-env-Append;,
3386 &f-link-env-AppendUnique;
3387 and &f-link-env-PrependUnique;.
3388 </para>
3389 </listitem>
3390   </varlistentry>
3391   <varlistentry id="f-PrependENVPath">
3392     <term><replaceable>env</replaceable>.<methodname>PrependENVPath</methodname>(<parameter>name, newpath, [envname, sep, delete_existing=True]</parameter>)</term>
3393     <listitem><para>
3394 Prepend path elements specified by <parameter>newpath</parameter>
3395 to the given search path string or list <parameter>name</parameter>
3396 in mapping <parameter>envname</parameter> in the &consenv;.
3397 Supplying <parameter>envname</parameter> is optional:
3398 the default is the execution environment &cv-link-ENV;.
3399 Optional <parameter>sep</parameter> is used as the search path separator,
3400 the default is the platform's separator (<systemitem>os.pathsep</systemitem>).
3401 A path element will only appear once.
3402 Any duplicates in <parameter>newpath</parameter> are dropped,
3403 keeping the first appearing (to preserve path order).
3404 If <parameter>delete_existing</parameter>
3405 is <constant>False</constant>
3406 any addition duplicating an existing path element is ignored;
3407 if <parameter>delete_existing</parameter>
3408 is <constant>True</constant> (the default) the existing value will
3409 be dropped and the path element will be inserted at the beginning.
3410 To help maintain uniqueness all paths are normalized (using
3411 <systemitem>os.path.normpath</systemitem>
3413 <systemitem>os.path.normcase</systemitem>).
3414 </para>
3416 <para>
3417 Example:
3418 </para>
3420 <example_commands>
3421 print('before:', env['ENV']['INCLUDE'])
3422 include_path = '/foo/bar:/foo'
3423 env.PrependENVPath('INCLUDE', include_path)
3424 print('after:', env['ENV']['INCLUDE'])
3425 </example_commands>
3427 <para>Yields:</para>
3429 <screen>
3430 before: /biz:/foo
3431 after: /foo/bar:/foo:/biz
3432 </screen>
3434 <para>
3435 See also &f-link-env-AppendENVPath;.
3436 </para>
3438 </listitem>
3439   </varlistentry>
3440   <varlistentry id="f-PrependUnique">
3441     <term><replaceable>env</replaceable>.<methodname>PrependUnique</methodname>(<parameter>key=val, [...], [delete_existing=False]</parameter>)</term>
3442     <listitem><para>
3443 Prepend values to &consvars; in the current &consenv;,
3444 maintaining uniqueness.
3445 Works like &f-link-env-Append;,
3446 except that values are added to the front,
3447 rather than the end, of the &consvar;,
3448 and values that would become duplicates
3449 are not added.
3450 If <parameter>delete_existing</parameter>
3451 is set to a true value, then for any duplicate,
3452 the existing instance of <parameter>val</parameter> is first removed,
3453 then <parameter>val</parameter> is inserted,
3454 having the effect of moving it to the front.
3455 </para>
3457 <para>
3458 Example:
3459 </para>
3461 <example_commands>
3462 env.PrependUnique(CCFLAGS='-g', FOO=['foo.yyy'])
3463 </example_commands>
3465 <para>
3466 See also &f-link-env-Append;,
3467 &f-link-env-AppendUnique;
3468 and &f-link-env-Prepend;.
3469 </para>
3470 </listitem>
3471   </varlistentry>
3472   <varlistentry id="f-Progress">
3473     <term><function>Progress</function>(<parameter>callable, [interval]</parameter>)</term>
3474     <term><function>Progress</function>(<parameter>string, [interval, file, overwrite]</parameter>)</term>
3475     <term><function>Progress</function>(<parameter>list_of_strings, [interval, file, overwrite]</parameter>)</term>
3476     <listitem><para>
3477 Allows SCons to show progress made during the build
3478 by displaying a string or calling a function while
3479 evaluating Nodes (e.g. files).
3480 </para>
3482 <para>
3483 If the first specified argument is a Python callable
3484 (a function or an object that has a
3485 <methodname>__call__</methodname> method),
3486 the function will be called
3487 once every
3488 <varname>interval</varname>
3489 times a Node is evaluated (default <constant>1</constant>).
3490 The callable will be passed the evaluated Node
3491 as its only argument.
3492 (For future compatibility,
3493 it's a good idea to also add
3494 <parameter>*args</parameter>
3496 <parameter>**kwargs</parameter>
3497 as arguments to your function or method signatures.
3498 This will prevent the code from breaking
3499 if &SCons; ever changes the interface
3500 to call the function with additional arguments in the future.)
3501 </para>
3503 <para>
3504 An example of a simple custom progress function
3505 that prints a string containing the Node name
3506 every 10 Nodes:
3507 </para>
3509 <example_commands>
3510 def my_progress_function(node, *args, **kwargs):
3511     print('Evaluating node %s!' % node)
3512 Progress(my_progress_function, interval=10)
3513 </example_commands>
3515 <para>
3516 A more complicated example of a custom progress display object
3517 that prints a string containing a count
3518 every 100 evaluated Nodes.
3519 Note the use of
3520 <literal>\r</literal>
3521 (a carriage return)
3522 at the end so that the string
3523 will overwrite itself on a display:
3524 </para>
3526 <example_commands>
3527 import sys
3528 class ProgressCounter(object):
3529     count = 0
3530     def __call__(self, node, *args, **kw):
3531         self.count += 100
3532         sys.stderr.write('Evaluated %s nodes\r' % self.count)
3534 Progress(ProgressCounter(), interval=100)
3535 </example_commands>
3537 <para>
3538 If the first argument to
3539 &f-Progress; is a string or list of strings,
3540 it is taken as text to be displayed every
3541 <varname>interval</varname>
3542 evaluated Nodes.
3543 If the first argument is a list of strings,
3544 then each string in the list will be displayed
3545 in rotating fashion every
3546 <varname>interval</varname>
3547 evaluated Nodes.
3548 </para>
3550 <para>
3551 The default is to print the string on standard output.
3552 An alternate output stream
3553 may be specified with the
3554 <parameter>file</parameter>
3555 keyword argument, which the
3556 caller must pass already opened.
3557 </para>
3559 <para>
3560 The following will print a series of dots
3561 on the error output,
3562 one dot for every 100 evaluated Nodes:
3563 </para>
3565 <example_commands>
3566 import sys
3567 Progress('.', interval=100, file=sys.stderr)
3568 </example_commands>
3570 <para>
3571 If the string contains the verbatim substring
3572 <literal>$TARGET;</literal>,
3573 it will be replaced with the Node.
3574 Note that, for performance reasons, this is
3575 <emphasis>not</emphasis>
3576 a regular SCons variable substitution,
3577 so you can not use other variables
3578 or use curly braces.
3579 The following example will print the name of
3580 every evaluated Node,
3581 using a carriage return)
3582 (<literal>\r</literal>)
3583 to cause each line to overwritten by the next line,
3584 and the
3585 <parameter>overwrite</parameter>
3586 keyword argument (default <literal>False</literal>)
3587 to make sure the previously-printed
3588 file name is overwritten with blank spaces:
3589 </para>
3591 <example_commands>
3592 import sys
3593 Progress('$TARGET\r', overwrite=True)
3594 </example_commands>
3596 <para>
3597 A list of strings can be used to implement a "spinner"
3598 on the user's screen as follows, changing every
3599 five evaluated Nodes:
3600 </para>
3602 <example_commands>
3603 Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
3604 </example_commands>
3605 </listitem>
3606   </varlistentry>
3607   <varlistentry id="f-Pseudo">
3608     <term><function>Pseudo</function>(<parameter>target, ...</parameter>)</term>
3609     <term><replaceable>env</replaceable>.<methodname>Pseudo</methodname>(<parameter>target, ...</parameter>)</term>
3610     <listitem><para>
3611 Marks <parameter>target</parameter> as a pseudo target,
3612 not representing the production of any physical target file.
3613 If any pseudo <parameter>target</parameter> does exist,
3614 &SCons; will abort the build with an error.
3615 Multiple targets can be passed in a single call,
3616 and may be strings and/or Nodes.
3617 Returns a list of the affected target nodes.
3618 </para>
3620 <para>
3621 &f-Pseudo; may be useful in conjuction with a builder
3622 call (such as &f-link-Command;) which does not create a physical target,
3623 and the behavior if the target accidentally existed would be incorrect.
3624 This is similar in concept to the GNU <application>make</application>
3625 <literal>.PHONY</literal> target.
3626 &SCons; also provides a powerful target alias capability
3627 (see &f-link-Alias;) which may provide more flexibility
3628 in many situations when defining target names that are not directly built.
3629 </para>
3630 </listitem>
3631   </varlistentry>
3632   <varlistentry id="f-PyPackageDir">
3633     <term><function>PyPackageDir</function>(<parameter>modulename</parameter>)</term>
3634     <term><replaceable>env</replaceable>.<methodname>PyPackageDir</methodname>(<parameter>modulename</parameter>)</term>
3635     <listitem><para>
3636 Finds the location of <parameter>modulename</parameter>,
3637 which can be a string or a sequence of strings,
3638 each representing the name of a &Python; module.
3639 Construction variables are expanded in
3640 <parameter>modulename</parameter>.
3641 Returns a Directory Node (see &f-link-Dir;),
3642 or a list of Directory Nodes if
3643 <parameter>modulename</parameter> is a sequence.
3644 <literal>None</literal> is returned for any module not found.
3645 </para>
3647 <para>
3648 When a Tool module which is installed as a
3649 &Python; module is used, you need
3650 to specify a <parameter>toolpath</parameter> argument to
3651 &f-link-Tool;,
3652 &f-link-Environment;
3653 or &f-link-Clone;,
3654 as tools outside the standard project locations
3655 (<filename>site_scons/site_tools</filename>)
3656 will not be found otherwise.
3657 Using &f-PyPackageDir; allows this path to be
3658 discovered at runtime instead of hardcoding the path.
3659 </para>
3661 <para>
3662 Example:
3663 </para>
3665 <example_commands>
3666 env = Environment(
3667     tools=["default", "ExampleTool"],
3668     toolpath=[PyPackageDir("example_tool")]
3670 </example_commands>
3671 </listitem>
3672   </varlistentry>
3673   <varlistentry id="f-Replace">
3674     <term><replaceable>env</replaceable>.<methodname>Replace</methodname>(<parameter>key=val, [...]</parameter>)</term>
3675     <listitem><para>
3676 Replaces &consvars; in the Environment
3677 with the specified keyword arguments.
3678 </para>
3680 <para>
3681 Example:
3682 </para>
3684 <example_commands>
3685 env.Replace(CCFLAGS='-g', FOO='foo.xxx')
3686 </example_commands>
3687 </listitem>
3688   </varlistentry>
3689   <varlistentry id="f-Repository">
3690     <term><function>Repository</function>(<parameter>directory</parameter>)</term>
3691     <term><replaceable>env</replaceable>.<methodname>Repository</methodname>(<parameter>directory</parameter>)</term>
3692     <listitem><para>
3693 Sets
3694 <parameter>directory</parameter>
3695 as a repository to be searched for files contributing to the build.
3696 Multiple calls to
3697 &f-Repository;
3698 are allowed,
3699 with repositories searched in the given order.
3700 Repositories specified via command-line option
3701 have higher priority.
3702 </para>
3704 <para>
3706 &scons;,
3707 a repository is partial or complete copy of the source tree,
3708 from the top-level directory down,
3709 containing source files
3710 that can be used to build targets in
3711 the current worktree.
3712 Repositories can also contain derived files.
3713 An example might be an official source tree maintained by an integrator.
3714 If a repository contains derived files,
3715 they should be the result of building with &SCons;,
3716 so a signature database (sconsign) is present
3717 in the repository,
3718 allowing better decisions on whether they are
3719 up-to-date or not.
3720 </para>
3722 <para>
3723 Note that if an up-to-date derived file
3724 already exists in a repository,
3725 &scons; will
3726 <emphasis>not</emphasis>
3727 make a copy in the local directory tree.
3728 If you need a local copy to be made,
3729 use the &f-link-Local; method.
3730 </para>
3731 </listitem>
3732   </varlistentry>
3733   <varlistentry id="f-Requires">
3734     <term><function>Requires</function>(<parameter>target, prerequisite</parameter>)</term>
3735     <term><replaceable>env</replaceable>.<methodname>Requires</methodname>(<parameter>target, prerequisite</parameter>)</term>
3736     <listitem><para>
3737 Specifies an order-only relationship
3738 between <parameter>target</parameter>
3739 and <parameter>prerequisite</parameter>.
3740 The prerequisites
3741 will be (re)built, if necessary,
3742 <emphasis>before</emphasis>
3743 the target file(s),
3744 but the target file(s) do not actually
3745 depend on the prerequisites
3746 and will not be rebuilt simply because
3747 the prerequisite file(s) change.
3748 <parameter>target</parameter> and
3749 <parameter>prerequisite</parameter> may each
3750 be a string or Node, or a list of strings or Nodes.
3751 If there are multiple
3752 <parameter>target</parameter> values,
3753 the prerequisite(s) are added to each one.
3754 Returns a list of the affected target nodes.
3755 </para>
3757 <para>
3758 Example:
3759 </para>
3761 <example_commands>
3762 env.Requires('foo', 'file-that-must-be-built-before-foo')
3763 </example_commands>
3764 </listitem>
3765   </varlistentry>
3766   <varlistentry id="f-Return">
3767     <term><function>Return</function>(<parameter>[vars..., stop=True]</parameter>)</term>
3768     <listitem><para>
3769 Return to the calling SConscript, optionally
3770 returning the values of variables named in
3771 <varname>vars</varname>.
3772 Multiple strings containing variable names may be passed to
3773 &f-Return;. A string containing white space
3774 is split into individual variable names.
3775 Returns the value if one variable is specified,
3776 else returns a tuple of values.
3777 Returns an empty tuple if <parameter>vars</parameter>
3778 is omitted.
3779 </para>
3781 <para>
3782 By default &Return; stops processing the current SConscript
3783 and returns immediately.
3784 The optional
3785 <literal>stop</literal>
3786 keyword argument
3787 may be set to a false value
3788 to continue processing the rest of the SConscript
3789 file after the
3790 &f-Return;
3791 call (this was the default behavior prior to SCons 0.98.)
3792 However, the values returned
3793 are still the values of the variables in the named
3794 <varname>vars</varname>
3795 at the point
3796 &f-Return;
3797 was called.
3798 </para>
3800 <para>
3801 Examples:
3802 </para>
3804 <example_commands>
3805 # Returns no values (evaluates False)
3806 Return()
3808 # Returns the value of the 'foo' Python variable.
3809 Return("foo")
3811 # Returns the values of the Python variables 'foo' and 'bar'.
3812 Return("foo", "bar")
3814 # Returns the values of Python variables 'val1' and 'val2'.
3815 Return('val1 val2')
3816 </example_commands>
3817 </listitem>
3818   </varlistentry>
3819   <varlistentry id="f-Scanner">
3820     <term><function>Scanner</function>(<parameter>function, [name, argument, skeys, path_function, node_class, node_factory, scan_check, recursive]</parameter>)</term>
3821     <term><replaceable>env</replaceable>.<methodname>Scanner</methodname>(<parameter>function, [name, argument, skeys, path_function, node_class, node_factory, scan_check, recursive]</parameter>)</term>
3822     <listitem><para>
3823 Creates a Scanner object for
3824 the specified
3825 <parameter>function</parameter>.
3826 See manpage section "Scanner Objects"
3827 for a complete explanation of the arguments and behavior.
3828 </para>
3829 </listitem>
3830   </varlistentry>
3831   <varlistentry id="f-SConscript">
3832     <term><function>SConscript</function>(<parameter>scriptnames, [exports, variant_dir, duplicate, must_exist]</parameter>)</term>
3833     <term><replaceable>env</replaceable>.<methodname>SConscript</methodname>(<parameter>scriptnames, [exports, variant_dir, duplicate, must_exist]</parameter>)</term>
3834     <term><function>SConscript</function>(<parameter>dirs=subdirs, [name=scriptname, exports, variant_dir, duplicate, must_exist]</parameter>)</term>
3835     <term><replaceable>env</replaceable>.<methodname>SConscript</methodname>(<parameter>dirs=subdirs, [name=scriptname, exports, variant_dir, duplicate, must_exist]</parameter>)</term>
3836     <listitem><para>
3837 Executes subsidiary SConscript (build configuration) file(s).
3838 There are two ways to call the
3839 &f-SConscript; function.
3840 </para>
3842 <para>
3843 The first calling style is to supply
3844 one or more SConscript file names
3845 as the first positional argument,
3846 which can be a string or a list of strings.
3847 If there is a second positional argument,
3848 it is treated as if the
3849 <varname>exports</varname>
3850 keyword argument had been given (see below).
3851 Examples:
3852 </para>
3853 <example_commands>
3854 SConscript('SConscript')  # run SConscript in the current directory
3855 SConscript('src/SConscript')  # run SConscript in the src directory
3856 SConscript(['src/SConscript', 'doc/SConscript'])
3857 SConscript(Split('src/SConscript doc/SConscript'))
3858 config = SConscript('MyConfig.py')
3859 </example_commands>
3861 <para>
3862 The second calling style is to omit the positional argument naming
3863 the script and instead specify directory names using the
3864 <varname>dirs</varname> keyword argument.
3865 The value can be a string or list of strings.
3866 In this case,
3867 &scons;
3868 will execute a subsidiary configuration file named
3869 &SConscript; (by default)
3870 in each of the specified directories.
3871 You may specify a name other than
3872 &SConscript;
3873 by supplying an optional
3874 <varname>name</varname>=<replaceable>scriptname</replaceable>
3875 keyword argument.
3876 The first three examples below have the same effect
3877 as the first three examples above:
3878 </para>
3879 <example_commands>
3880 SConscript(dirs='.')  # run SConscript in the current directory
3881 SConscript(dirs='src')  # run SConscript in the src directory
3882 SConscript(dirs=['src', 'doc'])
3883 SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
3884 </example_commands>
3886 <para>
3887 The optional
3888 <varname>exports</varname>
3889 keyword argument specifies variables to make available
3890 for use by the called SConscripts,
3891 which are evaluated in an isolated context
3892 and otherwise do not have access to local variables
3893 from the calling SConscript.
3894 The value may be a string or list of strings representing
3895 variable names, or a dictionary mapping local names to
3896 the names they can be imported by.
3897 For the first (scriptnames) calling style,
3898 a second positional argument will also be interpreted as
3899 <varname>exports</varname>;
3900 the second (directory) calling style accepts no
3901 positional arguments and must use the keyword form.
3902 These variables are locally exported only to the called
3903 SConscript file(s), and take precedence over any same-named
3904 variables in the global pool managed by the
3905 &f-link-Export;
3906 function.
3907 <!-- If multiple dirs are provided, each script gets a fresh export. -->
3908 The subsidiary SConscript files
3909 must use the
3910 &f-link-Import;
3911 function to import the variables into their local scope.
3912 Examples:
3913 </para>
3914 <example_commands>
3915 foo = SConscript('sub/SConscript', exports='env')
3916 SConscript('dir/SConscript', exports=['env', 'variable'])
3917 SConscript(dirs='subdir', exports='env variable')
3918 SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
3919 </example_commands>
3921 <para>
3922 If the optional
3923 <varname>variant_dir</varname>
3924 argument is present, it causes an effect equivalent to the
3925 &f-link-VariantDir; function,
3926 but in effect only within the scope of the &f-SConscript; call.
3927 The <varname>variant_dir</varname>
3928 argument is interpreted relative to the directory of the
3929 <emphasis>calling</emphasis> SConscript file.
3930 The source directory is the directory in which the
3931 <emphasis>called</emphasis> SConscript
3932 file resides and the SConscript
3933 file is evaluated as if it were in the
3934 <varname>variant_dir</varname>
3935 directory. Thus:
3936 </para>
3937 <example_commands>
3938 SConscript('src/SConscript', variant_dir='build')
3939 </example_commands>
3941 <para>
3942 is equivalent to:
3943 </para>
3945 <example_commands>
3946 VariantDir('build', 'src')
3947 SConscript('build/SConscript')
3948 </example_commands>
3950 <para>
3951 If the sources are in the same directory as the
3952 &SConstruct;,
3953 </para>
3955 <example_commands>
3956 SConscript('SConscript', variant_dir='build')
3957 </example_commands>
3959 <para>
3960 is equivalent to:
3961 </para>
3963 <example_commands>
3964 VariantDir('build', '.')
3965 SConscript('build/SConscript')
3966 </example_commands>
3968 <para>
3969 The optional
3970 <varname>duplicate</varname> argument is
3971 interpreted as for &f-link-VariantDir;.
3972 If the <varname>variant_dir</varname> argument
3973 is omitted, the <varname>duplicate</varname> argument is ignored.
3974 See the description of
3975 &f-link-VariantDir;
3976 for additional details and restrictions.
3977 </para>
3979 <para>
3980 <!--
3982 <varname>variant_dir</varname>
3983 and"
3984 <varname>src_dir</varname>
3985 are both present,
3986 xxxxx everything is in a state of confusion.
3987 </para>
3988 <example_commands>
3989 SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
3990 runs src/SConscript in build/src, but
3991 SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
3992 runs lib/SConscript (in lib!).  However,
3993 SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
3994 runs src/SConscript in build.  Moreover,
3995 SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
3996 runs src/lib/SConscript in build/lib.  Moreover,
3997 SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
3998 can't find build/src/lib/SConscript, even though it ought to exist.
3999 </example_commands>
4000 <para>
4001 is equivalent to
4002 </para>
4003 <example_commands>
4004 ????????????????
4005 </example_commands>
4006 <para>
4007 and what about this alternative?
4008 TODO??? SConscript('build/SConscript', src_dir='src')
4010 </para>
4012 <para>
4013 If the optional
4014 <varname>must_exist</varname>
4015 is <constant>True</constant> (the default),
4016 an exception is raised if a requested
4017 SConscript file is not found.
4018 To allow missing scripts to be silently ignored
4019 (the default behavior prior to &SCons; version 3.1),
4020 pass
4021 <literal>must_exist=False</literal> in the &f-SConscript; call.
4022 </para>
4024 <para>
4025 <emphasis>Changed in 4.6.0</emphasis>: <parameter>must_exist</parameter>
4026 now defaults to <constant>True</constant>.
4027 </para>
4029 <para>
4030 Here are some composite examples:
4031 </para>
4033 <example_commands>
4034 # collect the configuration information and use it to build src and doc
4035 shared_info = SConscript('MyConfig.py')
4036 SConscript('src/SConscript', exports='shared_info')
4037 SConscript('doc/SConscript', exports='shared_info')
4038 </example_commands>
4040 <example_commands>
4041 # build debugging and production versions.  SConscript
4042 # can use Dir('.').path to determine variant.
4043 SConscript('SConscript', variant_dir='debug', duplicate=0)
4044 SConscript('SConscript', variant_dir='prod', duplicate=0)
4045 </example_commands>
4047 <example_commands>
4048 # build debugging and production versions.  SConscript
4049 # is passed flags to use.
4050 opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
4051 SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
4052 opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
4053 SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
4054 </example_commands>
4056 <example_commands>
4057 # build common documentation and compile for different architectures
4058 SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
4059 SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
4060 SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
4061 </example_commands>
4063 <para>
4064 &f-SConscript; returns the values of any variables
4065 named by the executed SConscript file(s) in arguments
4066 to the &f-link-Return; function.
4067 If a single &f-SConscript; call causes multiple scripts to
4068 be executed, the return value is a tuple containing
4069 the returns of each of the scripts. If an executed
4070 script does not explicitly call &Return;, it returns
4071 <constant>None</constant>.
4072 </para>
4074 </listitem>
4075   </varlistentry>
4076   <varlistentry id="f-SConscriptChdir">
4077     <term><function>SConscriptChdir</function>(<parameter>value</parameter>)</term>
4078     <listitem><para>
4079 By default,
4080 &scons;
4081 changes its working directory
4082 to the directory in which each
4083 subsidiary SConscript file lives
4084 while reading and processing that script.
4085 This behavior may be disabled
4086 by specifying an argument which
4087 evaluates false, in which case
4088 &scons;
4089 will stay in the top-level directory
4090 while reading all SConscript files.
4091 (This may be necessary when building from repositories,
4092 when all the directories in which SConscript files may be found
4093 don't necessarily exist locally.)
4094 You may enable and disable
4095 this ability by calling
4096 &f-SConscriptChdir;
4097 multiple times.
4098 </para>
4100 <para>
4101 Example:
4102 </para>
4104 <example_commands>
4105 SConscriptChdir(False)
4106 SConscript('foo/SConscript')    # will not chdir to foo
4107 SConscriptChdir(True)
4108 SConscript('bar/SConscript')    # will chdir to bar
4109 </example_commands>
4110 </listitem>
4111   </varlistentry>
4112   <varlistentry id="f-SConsignFile">
4113     <term><function>SConsignFile</function>(<parameter>[name, dbm_module]</parameter>)</term>
4114     <term><replaceable>env</replaceable>.<methodname>SConsignFile</methodname>(<parameter>[name, dbm_module]</parameter>)</term>
4115     <listitem><para>
4116 Specify where to store the &SCons; file signature database,
4117 and which database format to use.
4118 This may be useful to specify alternate
4119 database files and/or file locations for different types of builds.
4120 </para>
4121 <para>
4122 The optional <parameter>name</parameter> argument
4123 is the base name of the database file(s).
4124 If not an absolute path name,
4125 these are placed relative to the directory containing the
4126 top-level &SConstruct; file.
4127 The default is
4128 <filename>.sconsign</filename>.
4129 The actual database file(s) stored on disk
4130 may have an appropriate suffix appended
4131 by the chosen
4132 <parameter>dbm_module</parameter>
4133 </para>
4134 <para>
4135 The optional <parameter>dbm_module</parameter>
4136 argument specifies which
4137 &Python; database module to use
4138 for reading/writing the file.
4139 The module must be imported first;
4140 then the imported module name
4141 is passed as the argument.
4142 The default is a custom
4143 <systemitem>SCons.dblite</systemitem>
4144 module that uses pickled
4145 &Python; data structures,
4146 which works on all &Python; versions.
4147 See documentation of the &Python;
4148 <systemitem>dbm</systemitem> module
4149 for other available types.
4150 </para>
4151 <para>
4152 If called with no arguments,
4153 the database will default to
4154 <filename>.sconsign.dblite</filename>
4155 in the top directory of the project,
4156 which is also the default if
4157 if &f-SConsignFile; is not called.
4158 </para>
4159 <para>
4160 The setting is global, so the only difference
4161 between the global function and the environment method form
4162 is variable expansion on <parameter>name</parameter>.
4163 There should only be one active call to this
4164 function/method in a given build setup.
4165 </para>
4166 <para>
4168 <parameter>name</parameter>
4169 is set to
4170 <constant>None</constant>,
4171 &scons;
4172 will store file signatures
4173 in a separate
4174 <filename>.sconsign</filename>
4175 file in each directory,
4176 not in a single combined database file.
4177 This is a backwards-compatibility measure to support
4178 what was the default behavior
4179 prior to &SCons; 0.97 (i.e. before 2008).
4180 Use of this mode is discouraged and may be
4181 deprecated in a future &SCons; release.
4182 </para>
4184 <para>
4185 Examples:
4186 </para>
4188 <example_commands>
4189 # Explicitly stores signatures in ".sconsign.dblite"
4190 # in the top-level SConstruct directory (the default behavior).
4191 SConsignFile()
4193 # Stores signatures in the file "etc/scons-signatures"
4194 # relative to the top-level SConstruct directory.
4195 # SCons will add a database suffix to this name.
4196 SConsignFile("etc/scons-signatures")
4198 # Stores signatures in the specified absolute file name.
4199 # SCons will add a database suffix to this name.
4200 SConsignFile("/home/me/SCons/signatures")
4202 # Stores signatures in a separate .sconsign file
4203 # in each directory.
4204 SConsignFile(None)
4206 # Stores signatures in a GNU dbm format .sconsign file
4207 import dbm.gnu
4208 SConsignFile(dbm_module=dbm.gnu)
4209 </example_commands>
4210 </listitem>
4211   </varlistentry>
4212   <varlistentry id="f-SetDefault">
4213     <term><replaceable>env</replaceable>.<methodname>SetDefault</methodname>(<parameter>key=val, [...]</parameter>)</term>
4214     <listitem><para>
4215 Sets &consvars; to default values specified with the keyword
4216 arguments if (and only if) the variables are not already set.
4217 The following statements are equivalent:
4218 </para>
4220 <example_commands>
4221 env.SetDefault(FOO='foo')
4222 if 'FOO' not in env:
4223     env['FOO'] = 'foo'
4224 </example_commands>
4225 </listitem>
4226   </varlistentry>
4227   <varlistentry id="f-SetOption">
4228     <term><function>SetOption</function>(<parameter>name, value</parameter>)</term>
4229     <term><replaceable>env</replaceable>.<methodname>SetOption</methodname>(<parameter>name, value</parameter>)</term>
4230     <listitem><para>
4231 Sets &scons; option variable <parameter>name</parameter>
4232 to <parameter>value</parameter>.
4233 These options are all also settable via
4234 command-line options but the variable name
4235 may differ from the command-line option name -
4236 see the table for correspondences.
4237 A value set via command-line option will take
4238 precedence over one set with &f-SetOption;, which
4239 allows setting a project default in the scripts and
4240 temporarily overriding it via command line.
4241 &f-SetOption; calls can also be placed in the
4242 <filename>site_init.py</filename> file.
4243 </para>
4245 <para>
4246 See the documentation in the manpage for the
4247 corresponding command line option for information about each specific option.
4248 The <parameter>value</parameter> parameter is mandatory,
4249 for option values which are boolean in nature
4250 (that is, the command line option does not take an argument)
4251 use a <parameter>value</parameter>
4252 which evaluates to true (e.g. <constant>True</constant>,
4253 <constant>1</constant>) or false (e.g. <constant>False</constant>,
4254 <constant>0</constant>).
4255 </para>
4257 <para>
4258 Options which affect the reading and processing of SConscript files
4259 are not settable using &f-SetOption; since those files must
4260 be read in order to find the &f-SetOption; call in the first place.
4261 </para>
4263 <para>
4264 For project-specific options (sometimes called
4265 <firstterm>local options</firstterm>)
4266 added via an &f-link-AddOption; call,
4267 &f-SetOption; is available only after the
4268 &f-AddOption; call has completed successfully,
4269 and only if that call included the
4270 <parameter>settable=True</parameter> argument.
4271 </para>
4273 <para>
4274 The settable variables with their associated command-line options are:
4275 </para>
4277 <informaltable rowsep="1" colsep="1" frame="topbot">
4278 <tgroup cols="3">
4279 <thead>
4280 <row>
4281   <entry align="left">Settable name</entry>
4282   <entry align="left">Command-line options</entry>
4283   <entry align="left">Notes</entry>
4284 </row>
4285 </thead>
4287 <tbody>
4288 <row>
4289   <entry><varname>clean</varname></entry>
4290   <entry>
4291     <option>-c</option>,
4292     <option>--clean</option>,
4293     <option>--remove</option>
4294   </entry>
4295 </row>
4297 <row>
4298   <entry><varname>diskcheck</varname></entry>
4299   <entry><option>--diskcheck</option></entry>
4300 </row>
4302 <row>
4303   <entry><varname>duplicate</varname></entry>
4304   <entry><option>--duplicate</option></entry>
4305 </row>
4307 <row>
4308   <entry><varname>experimental</varname></entry>
4309   <entry><option>--experimental</option></entry>
4310   <entry><emphasis>since 4.2</emphasis></entry>
4311 </row>
4313 <row>
4314   <entry><varname>hash_chunksize</varname></entry>
4315   <entry><option>--hash-chunksize</option></entry>
4316   <entry>
4317     Actually sets <varname>md5_chunksize</varname>.
4318     <emphasis>since 4.2</emphasis>
4319   </entry>
4320 </row>
4322 <row>
4323   <entry><varname>hash_format</varname></entry>
4324   <entry><option>--hash-format</option></entry>
4325   <entry><emphasis>since 4.2</emphasis></entry>
4326 </row>
4328 <row>
4329   <entry><varname>help</varname></entry>
4330   <entry><option>-h</option>, <option>--help</option></entry>
4331 </row>
4333 <row>
4334   <entry><varname>implicit_cache</varname></entry>
4335   <entry><option>--implicit-cache</option></entry>
4336 </row>
4338 <row>
4339   <entry><varname>implicit_deps_changed</varname></entry>
4340   <entry><option>--implicit-deps-changed</option></entry>
4341   <entry>
4342     Also sets <varname>implicit_cache</varname>.
4343     <emphasis>(settable since 4.2)</emphasis>
4344   </entry>
4345 </row>
4347 <row>
4348   <entry><varname>implicit_deps_unchanged</varname></entry>
4349   <entry><option>--implicit-deps-unchanged</option></entry>
4350   <entry>
4351     Also sets <varname>implicit_cache</varname>.
4352     <emphasis>(settable since 4.2)</emphasis>
4353   </entry>
4354 </row>
4356 <row>
4357   <entry><varname>max_drift</varname></entry>
4358   <entry><option>--max-drift</option></entry>
4359 </row>
4361 <row>
4362   <entry><varname>md5_chunksize</varname></entry>
4363   <entry><option>--md5-chunksize</option></entry>
4364 </row>
4366 <row>
4367   <entry><varname>no_exec</varname></entry>
4368   <entry>
4369     <option>-n</option>,
4370     <option>--no-exec</option>,
4371     <option>--just-print</option>,
4372     <option>--dry-run</option>,
4373     <option>--recon</option>
4374   </entry>
4375 </row>
4377 <row>
4378   <entry><varname>no_progress</varname></entry>
4379   <entry><option>-Q</option></entry>
4380   <entry>See
4381     <footnote>
4382       <para>If <varname>no_progress</varname> is set via &f-SetOption;
4383       in an SConscript file
4384       (but not if set in a <filename>site_init.py</filename> file)
4385       there will still be an initial status message about
4386       reading SConscript files since &SCons; has
4387       to start reading them before it can see the
4388       &f-SetOption;.
4389       </para>
4390     </footnote>
4391   </entry>
4392 </row>
4394 <row>
4395   <entry><varname>num_jobs</varname></entry>
4396   <entry><option>-j</option>, <option>--jobs</option></entry>
4397 </row>
4399 <row>
4400   <entry><varname>random</varname></entry>
4401   <entry><option>--random</option></entry>
4402 </row>
4404 <row>
4405   <entry><varname>silent</varname></entry>
4406   <entry>
4407     <option>-s</option>,
4408     <option>--silent</option>,
4409     <option>--quiet</option>
4410   </entry>
4411 </row>
4413 <row>
4414   <entry><varname>stack_size</varname></entry>
4415   <entry><option>--stack-size</option></entry>
4416 </row>
4418 <row>
4419   <entry><varname>warn</varname></entry>
4420   <entry><option>--warn</option></entry>
4421 </row>
4423 </tbody>
4424 </tgroup>
4425 </informaltable>
4427 <para>
4428 Example:
4429 </para>
4431 <example_commands>
4432 SetOption('max_drift', 0)
4433 </example_commands>
4434 </listitem>
4435   </varlistentry>
4436   <varlistentry id="f-SideEffect">
4437     <term><function>SideEffect</function>(<parameter>side_effect, target</parameter>)</term>
4438     <term><replaceable>env</replaceable>.<methodname>SideEffect</methodname>(<parameter>side_effect, target</parameter>)</term>
4439     <listitem><para>
4440 Declares
4441 <parameter>side_effect</parameter>
4442 as a side effect of building
4443 <parameter>target</parameter>.
4444 Both
4445 <parameter>side_effect</parameter>
4447 <parameter>target</parameter>
4448 can be a list, a file name, or a node.
4449 A side effect is a target file that is created or updated
4450 as a side effect of building other targets.
4451 For example, a Windows PDB
4452 file is created as a side effect of building the .obj
4453 files for a static library,
4454 and various log files are created updated
4455 as side effects of various TeX commands.
4456 If a target is a side effect of multiple build commands,
4457 &scons;
4458 will ensure that only one set of commands
4459 is executed at a time.
4460 Consequently, you only need to use this method
4461 for side-effect targets that are built as a result of
4462 multiple build commands.
4463 </para>
4465 <para>
4466 Because multiple build commands may update
4467 the same side effect file,
4468 by default the
4469 <parameter>side_effect</parameter>
4470 target is
4471 <emphasis>not</emphasis>
4472 automatically removed
4473 when the
4474 <parameter>target</parameter>
4475 is removed by the
4476 <option>-c</option>
4477 option.
4478 (Note, however, that the
4479 <parameter>side_effect</parameter>
4480 might be removed as part of
4481 cleaning the directory in which it lives.)
4482 If you want to make sure the
4483 <parameter>side_effect</parameter>
4484 is cleaned whenever a specific
4485 <parameter>target</parameter>
4486 is cleaned,
4487 you must specify this explicitly
4488 with the
4489 &f-link-Clean;
4491 &f-env-Clean;
4492 function.
4493 </para>
4495 <para>
4496 This function returns the list of side effect Node objects that were successfully added.
4497 If the list of side effects contained any side effects that had already been added,
4498 they are not added and included in the returned list.
4499 </para>
4500 </listitem>
4501   </varlistentry>
4502   <varlistentry id="f-Split">
4503     <term><function>Split</function>(<parameter>arg</parameter>)</term>
4504     <term><replaceable>env</replaceable>.<methodname>Split</methodname>(<parameter>arg</parameter>)</term>
4505     <listitem><para>
4506 If <parameter>arg</parameter> is a string,
4507 splits on whitespace and returns a list of
4508 strings without whitespace.
4509 This mode is the most common case,
4510 and can be used to split a list of filenames
4511 (for example) rather than having to type them as a
4512 list of individually quoted words.
4513 If <parameter>arg</parameter> is a list or tuple
4514 returns the list or tuple unchanged.
4515 If <parameter>arg</parameter> is any other type of object,
4516 returns a list containing just the object.
4517 These non-string cases do not actually do any spliting,
4518 but allow an argument variable to be passed to
4519 &f-Split; without having to first check its type.
4520 </para>
4522 <para>
4523 Example:
4524 </para>
4526 <example_commands>
4527 files = Split("f1.c f2.c f3.c")
4528 files = env.Split("f4.c f5.c f6.c")
4529 files = Split("""
4530     f7.c
4531     f8.c
4532     f9.c
4533 """)
4534 </example_commands>
4535 </listitem>
4536   </varlistentry>
4537   <varlistentry id="f-subst">
4538     <term><replaceable>env</replaceable>.<methodname>subst</methodname>(<parameter>input, [raw, target, source, conv]</parameter>)</term>
4539     <listitem><para>
4540 Performs &consvar; interpolation
4541 (<firstterm>substitution</firstterm>)
4542 on <parameter>input</parameter>,
4543 which can be a string or a sequence.
4544 Substitutable elements take the form
4545 <literal>${<replaceable>expression</replaceable>}</literal>,
4546 although if there is no ambiguity in recognizing the element,
4547 the braces can be omitted.
4548 A literal <emphasis role="bold">$</emphasis> can be entered by
4549 using <emphasis role="bold">$$</emphasis>.
4550 </para>
4552 <para>
4553 By default,
4554 leading or trailing white space will
4555 be removed from the result,
4556 and all sequences of white space
4557 will be compressed to a single space character.
4558 Additionally, any
4559 <literal>$(</literal>
4561 <literal>$)</literal>
4562 character sequences will be stripped from the returned string,
4563 The optional
4564 <parameter>raw</parameter>
4565 argument may be set to
4566 <literal>1</literal>
4567 if you want to preserve white space and
4568 <literal>$(</literal>-<literal>$)</literal>
4569 sequences.
4571 <parameter>raw</parameter>
4572 argument may be set to
4573 <literal>2</literal>
4574 if you want to additionally discard
4575 all characters between any
4576 <literal>$(</literal>
4578 <literal>$)</literal>
4579 pairs
4580 (as is done for signature calculation).
4581 </para>
4583 <para>
4584 If <parameter>input</parameter> is a sequence
4585 (list or tuple),
4586 the individual elements of
4587 the sequence will be expanded,
4588 and the results will be returned as a list.
4589 </para>
4591 <para>
4592 The optional
4593 <parameter>target</parameter>
4595 <parameter>source</parameter>
4596 keyword arguments
4597 must be set to lists of
4598 target and source nodes, respectively,
4599 if you want the
4600 &cv-TARGET;,
4601 &cv-TARGETS;,
4602 &cv-SOURCE;
4604 &cv-SOURCES;
4605 to be available for expansion.
4606 This is usually necessary if you are
4607 calling
4608 &f-env-subst;
4609 from within a &Python; function used
4610 as an SCons action.
4611 </para>
4613 <para>
4614 Returned string values or sequence elements
4615 are converted to their string representation by default.
4616 The optional
4617 <parameter>conv</parameter>
4618 argument
4619 may specify a conversion function
4620 that will be used in place of
4621 the default.
4622 For example, if you want &Python; objects
4623 (including SCons Nodes)
4624 to be returned as &Python; objects,
4625 you can use a &Python;
4626 lambda expression to pass in an unnamed function
4627 that simply returns its unconverted argument.
4628 </para>
4630 <para>
4631 Example:
4632 </para>
4634 <example_commands>
4635 print(env.subst("The C compiler is: $CC"))
4637 def compile(target, source, env):
4638     sourceDir = env.subst(
4639         "${SOURCE.srcdir}",
4640         target=target,
4641         source=source
4642     )
4644 source_nodes = env.subst('$EXPAND_TO_NODELIST', conv=lambda x: x)
4645 </example_commands>
4646 </listitem>
4647   </varlistentry>
4648   <varlistentry id="f-Tag">
4649     <term><function>Tag</function>(<parameter>node, tags</parameter>)</term>
4650     <listitem><para>
4651 Annotates file or directory Nodes with
4652 information about how the
4653 &b-link-Package;
4654 Builder should package those files or directories.
4655 All Node-level tags are optional.
4656 </para>
4658 <para>
4659 Examples:
4660 </para>
4662 <example_commands>
4663 # makes sure the built library will be installed with 644 file access mode
4664 Tag(Library('lib.c'), UNIX_ATTR="0o644")
4666 # marks file2.txt to be a documentation file
4667 Tag('file2.txt', DOC)
4668 </example_commands>
4669 </listitem>
4670   </varlistentry>
4671   <varlistentry id="f-Tool">
4672     <term><function>Tool</function>(<parameter>name, [toolpath, key=value, ...]</parameter>)</term>
4673     <term><replaceable>env</replaceable>.<methodname>Tool</methodname>(<parameter>name, [toolpath, key=value, ...]</parameter>)</term>
4674     <listitem><para>
4675 Locates the tool specification module <parameter>name</parameter>
4676 and returns a callable tool object for that tool.
4677 When the environment method (&f-env-Tool;) form is used,
4678 the tool object is automatically called before the method returns
4679 to update <varname>env</varname>,
4680 and <parameter>name</parameter> is
4681 appended to the &cv-link-TOOLS;
4682 &consvar; in that environment.
4683 When the global function &f-Tool; form is used,
4684 the tool object is constructed but not called,
4685 as it lacks the context of an environment to update,
4686 and the returned object needs to be used to arrange for the call.
4687 </para>
4689 <para>
4690 The tool module is searched for in the tool search paths (see the
4691 <emphasis role="bold">Tools</emphasis> section in the manual page
4692 for details)
4693 and in any paths specified by the optional
4694 <parameter>toolpath</parameter> parameter,
4695 which must be a list of strings.
4696 If <parameter>toolpath</parameter> is omitted,
4697 the <parameter>toolpath</parameter>
4698 supplied when the environment was created,
4699 if any, is used.
4700 </para>
4702 <para>
4703 Any remaining keyword arguments are saved in
4704 the tool object,
4705 and will be passed to the tool module's
4706 <function>generate</function> function
4707 when the tool object is actually called.
4708 The <function>generate</function> function
4709 can update the &consenv; with &consvars; and arrange
4710 any other initialization
4711 needed to use the mechanisms that tool describes,
4712 and can use these extra arguments to help
4713 guide its actions.
4714 </para>
4716 <para>
4717 <emphasis>Changed in version  4.2:</emphasis>
4718 &f-env-Tool; now returns the tool object,
4719 previously it did not return (i.e. returned <constant>None</constant>).
4720 </para>
4722 <para>
4723 Examples:
4724 </para>
4726 <example_commands>
4727 env.Tool('gcc')
4728 env.Tool('opengl', toolpath=['build/tools'])
4729 </example_commands>
4731 <para>
4732 The returned tool object can be passed to an
4733 &f-link-Environment; or &f-link-Clone; call
4734 as part of the <parameter>tools</parameter> keyword argument,
4735 in which case the tool is applied to the environment being constructed,
4736 or it can be called directly,
4737 in which case a &consenv; to update must be
4738 passed as the argument.
4739 Either approach will also update the
4740 &cv-TOOLS; &consvar;.
4741 </para>
4743 <para>
4744 Examples:
4745 </para>
4747 <example_commands>
4748 env = Environment(tools=[Tool('msvc')])
4750 env = Environment()
4751 msvctool = Tool('msvc')
4752 msvctool(env)  # adds 'msvc' to the TOOLS variable
4753 gltool = Tool('opengl', toolpath = ['tools'])
4754 gltool(env)  # adds 'opengl' to the TOOLS variable
4755 </example_commands>
4756 </listitem>
4757   </varlistentry>
4758   <varlistentry id="f-ValidateOptions">
4759     <term><function>ValidateOptions</function>(<parameter>[throw_exception=False]</parameter>)</term>
4760     <listitem><para>
4761         Check that all the options specified on the command line are either
4762         &SCons; built-in options or defined via calls to &f-link-AddOption;.
4763         &SCons; will eventually fail on unknown options anyway, but calling
4764         this function allows the build to "fail fast" before executing
4765         expensive logic later in the build.
4766       </para>
4768       <para>
4769         This function should only be called after the last &f-AddOption;
4770         call in your &SConscript; logic.
4771         Be aware that some tools call &f-AddOption;, if you are getting
4772         error messages for arguments that they add, you will need to ensure
4773         that those tools are loaded before calling &f-ValidateOptions;.
4774       </para>
4776       <para>
4777         If there are any unknown command line options, &f-ValidateOptions;
4778         prints an error message and exits with an error exit status.
4779         If the optional <parameter>throw_exception</parameter> argument is
4780         <literal>True</literal> (default is <literal>False</literal>),
4781         a <exceptionname>SConsBadOptionError</exceptionname> is raised,
4782         giving an opportunity for the &SConscript; logic to catch that
4783         exception and handle invalid options appropriately. Note that
4784         this exception name needs to be imported (see the example below).
4785       </para>
4787       <para>
4788         A common build problem is typos (or thinkos) - a user enters an option
4789         that is just a little off the expected value, or perhaps a different
4790         word with a similar meaning.  It may be useful to abort the build
4791         before going too far down the wrong path. For example:
4792       </para>
4794       <screen>
4795 $ <userinput>scons --compilers=mingw</userinput>  # the correct flag is --compiler
4796       </screen>
4798       <para>
4799         Here &SCons; could go off and run a bunch of configure steps with
4800         the default value of <literal>--compiler</literal>, since the
4801         incorrect command line did not actually supply a value to it,
4802         costing developer time to track down why the configure logic
4803         made the "wrong" choices.  This example shows catching this:
4804       </para>
4806       <programlisting language="python">
4807 from SCons.Script.SConsOptions import SConsBadOptionError
4809 AddOption(
4810     '--compiler',
4811     dest='compiler',
4812     action='store',
4813     default='gcc',
4814     type='string',
4817 # ... other SConscript logic ...
4819 try:
4820     ValidateOptions(throw_exception=True)
4821 except SConsBadOptionError as e:
4822     print(f"ValidateOptions detects a fail: ", e.opt_str)
4823     Exit(3)
4824       </programlisting>
4826       <para><emphasis>New in version 4.5.0</emphasis></para>
4828     </listitem>
4829   </varlistentry>
4830   <varlistentry id="f-Value">
4831     <term><function>Value</function>(<parameter>value, [built_value], [name]</parameter>)</term>
4832     <term><replaceable>env</replaceable>.<methodname>Value</methodname>(<parameter>value, [built_value], [name]</parameter>)</term>
4833     <listitem><para>
4834 Returns a Node object representing the specified &Python;
4835 <parameter>value</parameter>.
4836 Value Nodes can be used as dependencies of targets.
4837 If the string representation of the Value Node
4838 changes between &SCons; runs, it is considered
4839 out-of-date and any targets depending on it will be rebuilt.
4840 Since Value Nodes have no filesystem representation,
4841 timestamps are not used; the timestamp deciders
4842 perform the same content-based up to date check.
4843 </para>
4844 <para>
4845 The optional
4846 <parameter>built_value</parameter>
4847 argument can be specified
4848 when the Value Node is created
4849 to indicate the Node should already be considered "built."
4850 </para>
4852 <para>
4853 The optional <parameter>name</parameter> parameter can be provided as an
4854 alternative name for the resulting <literal>Value</literal> node;
4855 this is advised if the <parameter>value</parameter> parameter
4856 cannot be converted to a string.
4857 </para>
4859 <para>
4860 Value Nodes have a
4861 <methodname>write</methodname>
4862 method that can be used to "build" a Value Node
4863 by setting a new value.
4864 The corresponding
4865 <methodname>read</methodname>
4866 method returns the built value of the Node.
4867 </para>
4869 <para>
4870 <emphasis>Changed in version 4.0:</emphasis>
4871 the <parameter>name</parameter> parameter was added.
4872 </para>
4874 <para>
4875 Examples:
4876 </para>
4878 <example_commands>
4879 env = Environment()
4881 def create(target, source, env):
4882     """Action function to create a file from a Value.
4884     Writes 'prefix=$SOURCE' into the file name given as $TARGET.
4885     """
4886     with open(str(target[0]), 'wb') as f:
4887         f.write(b'prefix=' + source[0].get_contents() + b'\n')
4889 # Fetch the prefix= argument, if any, from the command line.
4890 # Use /usr/local as the default.
4891 prefix = ARGUMENTS.get('prefix', '/usr/local')
4893 # Attach builder named Config to the construction environment
4894 # using the 'create' action function above.
4895 env['BUILDERS']['Config'] = Builder(action=create)
4896 env.Config(target='package-config', source=Value(prefix))
4898 def build_value(target, source, env):
4899     """Action function to "build" a Value.
4901     Writes contents of $SOURCE into $TARGET, thus updating if it existed.
4902     """
4903     target[0].write(source[0].get_contents())
4905 output = env.Value('before')
4906 input = env.Value('after')
4908 # Attach a builder named UpdateValue to the construction environment
4909 # using the 'build_value' action function above.
4910 env['BUILDERS']['UpdateValue'] = Builder(action=build_value)
4911 env.UpdateValue(target=Value(output), source=Value(input))
4912 </example_commands>
4913 </listitem>
4914   </varlistentry>
4915   <varlistentry id="f-VariantDir">
4916     <term><function>VariantDir</function>(<parameter>variant_dir, src_dir, [duplicate]</parameter>)</term>
4917     <term><replaceable>env</replaceable>.<methodname>VariantDir</methodname>(<parameter>variant_dir, src_dir, [duplicate]</parameter>)</term>
4918     <listitem><para>
4919 Sets up a mapping to define a variant build directory in
4920 <parameter>variant_dir</parameter>.
4921 <parameter>src_dir</parameter> must not be underneath
4922 <parameter>variant_dir</parameter>.
4923 A &f-VariantDir; mapping is global, even if called using the
4924 &f-env-VariantDir; form.
4925 &f-VariantDir;
4926 can be called multiple times with the same
4927 <parameter>src_dir</parameter>
4928 to set up multiple variant builds with different options.
4929 </para>
4931 <para>
4932 Note if <parameter>variant_dir</parameter>
4933 is not under the project top directory,
4934 target selection rules will not pick targets in the
4935 variant directory unless they are explicitly specified.
4936 </para>
4938 <para>
4939 When files in <parameter>variant_dir</parameter> are referenced,
4940 &SCons; backfills as needed with files from <parameter>src_dir</parameter>
4941 to create a complete build directory.
4942 By default, &SCons;
4943 physically duplicates the source files, SConscript files,
4944 and directory structure as needed into the variant directory.
4945 Thus, a build performed in the variant directory is guaranteed to be identical
4946 to a build performed in the source directory even if
4947 intermediate source files are generated during the build,
4948 or if preprocessors or other scanners search for included files
4949 using paths relative to the source file,
4950 or if individual compilers or other invoked tools are hard-coded
4951 to put derived files in the same directory as source files.
4952 Only the files &SCons; calculates are needed for the build are
4953 duplicated into <parameter>variant_dir</parameter>.
4954 If possible on the platform,
4955 the duplication is performed by linking rather than copying.
4956 This behavior is affected by the
4957 <option>--duplicate</option>
4958 command-line option.
4959 </para>
4961 <para>
4962 Duplicating the source files may be disabled by setting the
4963 <parameter>duplicate</parameter>
4964 argument to
4965 <constant>False</constant>.
4966 This will cause
4967 &SCons;
4968 to invoke Builders using the path names of source files in
4969 <parameter>src_dir</parameter>
4970 and the path names of derived files within
4971 <parameter>variant_dir</parameter>.
4972 This is more efficient than duplicating,
4973 and is safe for most builds;
4974 revert to <literal>duplicate=True</literal>
4975 if it causes problems.
4976 </para>
4978 <para>
4979 &f-VariantDir;
4980 works most naturally when used with a subsidiary SConscript file.
4981 The subsidiary SConscript file must be called as if it were in
4982 <parameter>variant_dir</parameter>,
4983 regardless of the value of
4984 <parameter>duplicate</parameter>.
4985 When calling an SConscript file, you can use the
4986 <parameter>exports</parameter> keyword argument
4987 to pass parameters (individually or as an appropriately set up environment)
4988 so the SConscript can pick up the right settings for that variant build.
4989 The SConscript must &f-link-Import; these to use them. Example:
4990 </para>
4992 <example_commands>
4993 env1 = Environment(...settings for variant1...)
4994 env2 = Environment(...settings for variant2...)
4996 # run src/SConscript in two variant directories
4997 VariantDir('build/variant1', 'src')
4998 SConscript('build/variant1/SConscript', exports={"env": env1})
4999 VariantDir('build/variant2', 'src')
5000 SConscript('build/variant2/SConscript', exports={"env": env2})
5001 </example_commands>
5003 <para>
5004 See also the
5005 &f-link-SConscript; function
5006 for another way to specify a variant directory
5007 in conjunction with calling a subsidiary SConscript file.
5008 </para>
5010 <para>
5011 More examples:
5012 </para>
5014 <example_commands>
5015 # use names in the build directory, not the source directory
5016 VariantDir('build', 'src', duplicate=0)
5017 Program('build/prog', 'build/source.c')
5019 # this builds both the source and docs in a separate subtree
5020 VariantDir('build', '.', duplicate=0)
5021 SConscript(dirs=['build/src','build/doc'])
5023 # same as previous example, but only uses SConscript
5024 SConscript(dirs='src', variant_dir='build/src', duplicate=0)
5025 SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
5026 </example_commands>
5027 </listitem>
5028   </varlistentry>
5029   <varlistentry id="f-WhereIs">
5030     <term><function>WhereIs</function>(<parameter>program, [path, pathext, reject]</parameter>)</term>
5031     <term><replaceable>env</replaceable>.<methodname>WhereIs</methodname>(<parameter>program, [path, pathext, reject]</parameter>)</term>
5032     <listitem><para>
5033 Searches for the specified executable
5034 <parameter>program</parameter>,
5035 returning the full path to the program
5036 or <constant>None</constant>.
5037 </para>
5038 <para>
5039 When called as a &consenv; method,
5040 searches the paths in the
5041 <parameter>path</parameter> keyword argument,
5042 or if <constant>None</constant> (the default)
5043 the paths listed in the &consenv;
5044 (<varname>env</varname><literal>['ENV']['PATH']</literal>).
5045 The external environment's path list
5046 (<literal>os.environ['PATH']</literal>)
5047 is used as a fallback if the key
5048 <varname>env</varname><literal>['ENV']['PATH']</literal>
5049 does not exist.
5050 </para>
5051 <para>
5052 On Windows systems, searches for executable
5053 programs with any of the file extensions listed in the
5054 <parameter>pathext</parameter> keyword argument,
5055 or if <constant>None</constant> (the default)
5056 the pathname extensions listed in the &consenv;
5057 (<varname>env</varname><literal>['ENV']['PATHEXT']</literal>).
5058 The external environment's pathname extensions list
5059 (<literal>os.environ['PATHEXT']</literal>)
5060 is used as a fallback if the key
5061 <varname>env</varname><literal>['ENV']['PATHEXT']</literal>
5062 does not exist.
5063 </para>
5064 <para>
5065 When called as a global function, uses the external
5066 environment's path
5067 <literal>os.environ['PATH']</literal>
5068 and path extensions
5069 <literal>os.environ['PATHEXT']</literal>,
5070 respectively, if
5071 <parameter>path</parameter> and
5072 <parameter>pathext</parameter> are
5073 <constant>None</constant>.
5074 </para>
5075 <para>
5076 Will not select any
5077 path name or names
5078 in the optional
5079 <parameter>reject</parameter>
5080 list.
5081 </para>
5083 </listitem>
5084   </varlistentry>
5085 </variablelist>