2 <!ENTITY % scons SYSTEM "../scons.mod">
4 <!ENTITY % builders-mod SYSTEM "builders.mod">
6 <!ENTITY % functions-mod SYSTEM "functions.mod">
8 <!ENTITY % tools-mod SYSTEM "tools.mod">
10 <!ENTITY % variables-mod SYSTEM "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>
19 A factory function to create an Action object for
21 <parameter>action</parameter>.
22 See the manpage section "Action Objects"
23 for a complete explanation of the arguments and behavior.
27 Note that the &f-env-Action;
28 form of the invocation will expand
29 &consvars; in any argument strings,
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.
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>
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.
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.
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)
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')
85 <varlistentry id="f-AddOption">
86 <term><function>AddOption</function>(<parameter>opt_str, ..., attr=value, ...</parameter>)</term>
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.
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.
106 In addition to the arguments and values supported by the
107 <systemitem>optparse</systemitem>
108 <function>add_option</function>
109 method, &f-AddOption;
111 <parameter>nargs</parameter>
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
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;
127 <parameter>default</parameter>
128 keyword argument in the &f-AddOption; call,
129 <constant>None</constant> is produced.
133 <systemitem>optparse</systemitem> recognizes
134 abbreviations of long option names,
135 as long as they can be unambiguously resolved.
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.
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.
151 Once a new command-line option has been added with
153 the option value may be accessed using
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
162 &f-link-env-SetOption;,
165 require overriding any default value.
167 value specified on the command line will
168 <emphasis>always</emphasis>
169 override a value set in an SConscript file.
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;.
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
208 help='installation prefix',
210 env = Environment(PREFIX=GetOption('prefix'))
213 <para>For that example,
214 the following help text would be produced:</para>
218 --prefix=DIR installation prefix
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.
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.
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>
254 Arranges for the specified
255 <parameter>action</parameter>
258 <parameter>target</parameter>
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.
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.
275 foo = Program('foo.c')
276 # remove execute permission from binary:
277 AddPostAction(foo, Chmod('$TARGET', "a-x"))
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>
286 Arranges for the specified
287 <parameter>action</parameter>
290 <parameter>target</parameter>
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.
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.
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:
318 foo = Program('foo.c')
319 AddPreAction(foo, 'pre_action')
324 <literal>pre_action</literal>
325 would be executed before
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.
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>
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.
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.
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.
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.
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.
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")
404 <varlistentry id="f-AllowSubstExceptions">
405 <term><function>AllowSubstExceptions</function>(<parameter>[exception, ...]</parameter>)</term>
407 Specifies the exceptions that will be ignored
408 when expanding &consvars;.
410 any &consvar; expansions that generate a
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.
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.
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)
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>
452 <parameter>target</parameter>
453 so that it is always assumed to be out-of-date,
454 and will always be rebuilt if needed.
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
462 <emphasis>always</emphasis>
463 be built if so specified.
464 Multiple targets can be passed in to a single call to
469 <varlistentry id="f-Append">
470 <term><replaceable>env</replaceable>.<methodname>Append</methodname>(<parameter>key=val, [...]</parameter>)</term>
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.
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.
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;):
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'))
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.
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;:
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>
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>
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>
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.
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'))
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.
610 Examples of adding multiple macros:
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'))
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.
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.
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'))
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.
654 See &cv-link-CPPDEFINES; for more details.
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;
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.
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;.
683 env.Append(CPPPATH=["#/include"])
687 See also &f-link-env-AppendUnique;,
688 &f-link-env-Prepend; and &f-link-env-PrependUnique;.
693 <varlistentry id="f-AppendENVPath">
694 <term><replaceable>env</replaceable>.<methodname>AppendENVPath</methodname>(<parameter>name, newpath, [envname, sep, delete_existing=False]</parameter>)</term>
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>).
723 print('before:', env['ENV']['INCLUDE'])
724 include_path = '/foo/bar:/foo'
725 env.AppendENVPath('INCLUDE', include_path)
726 print('after:', env['ENV']['INCLUDE'])
732 after: /biz:/foo/bar:/foo
736 See also &f-link-env-PrependENVPath;.
741 <varlistentry id="f-AppendUnique">
742 <term><replaceable>env</replaceable>.<methodname>AppendUnique</methodname>(<parameter>key=val, [...], [delete_existing=False]</parameter>)</term>
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
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.
761 env.AppendUnique(CCFLAGS='-g', FOO=['foo.yyy'])
765 See also &f-link-env-Append;,
767 and &f-link-env-PrependUnique;.
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>
775 Creates a Builder object for
777 <parameter>action</parameter>.
778 See the manpage section "Builder Objects"
779 for a complete explanation of the arguments and behavior.
784 <function>env.Builder</function>()
785 form of the invocation will expand
786 &consvars; in any arguments strings,
788 <parameter>action</parameter>
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.
797 form delays all variable expansion
798 until after the Builder object is actually called.
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>
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>.
814 <parameter>cache_dir</parameter>
816 <constant>None</constant>
817 disables derived file caching.
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
827 sets a global default
828 that will be used by all targets built
830 that do not set up environment-specific
831 caching by calling &f-env-CacheDir;.
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
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.
847 When derived-file caching
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.
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,
863 then place a copy of the built file in the cache,
864 identified by its &buildsig;, for future use.
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.
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.
883 may be disabled for any invocation
884 of &scons; by giving the
885 <option>--cache-disable</option>
887 cache updating may be disabled, leaving cache
888 fetching enabled, by giving the
889 <option>--cache-readonly</option> option.
894 <option>--cache-force</option>
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
904 <parameter>cache_dir</parameter>
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>)
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.
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.
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>
933 This specifies a list of files or directories which should be removed
934 whenever the targets are specified with the
937 The specified targets may be a list
938 or an individual target.
942 and create new targets or add files and directories to the
943 clean list for the specified targets.
947 Multiple files or directories should be specified
948 either as separate arguments to the
950 method, or as a list.
952 will also accept the return value of the &consenv;
960 function overrides calling
963 and any targets passed to both functions will
964 <emphasis>not</emphasis>
975 Clean('foo', ['bar', 'baz'])
976 Clean('dist', env.Program('hello', 'hello.c'))
977 Clean(['foo', 'bar'], 'something_else_to_clean')
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.
987 Clean(docdir, os.path.join(docdir, projectname))
991 <varlistentry id="f-Clone">
992 <term><replaceable>env</replaceable>.<methodname>Clone</methodname>(<parameter>[key=val, ...]</parameter>)</term>
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
999 See the manpage section "Construction Environments" for more details.
1008 env3 = env.Clone(CCFLAGS='-g')
1012 A list of <parameter>tools</parameter>
1013 and a <parameter>toolpath</parameter> may be specified,
1014 as in the &f-link-Environment; constructor:
1021 env4 = env.Clone(tools=['msvc', MyTool])
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;).
1033 # create an environment for compiling programs that use wxWidgets
1034 wx_env = env.Clone(parse_flags='!wx-config --cflags --cxxflags')
1038 The <parameter>variables</parameter>
1039 keyword argument is also recognized, to allow (re)initializing
1040 &consvars; from a <literal>Variables</literal> object.
1044 <emphasis>Changed in version 4.8.0:</emphasis>
1045 the <parameter>variables</parameter> parameter was added.
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>
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.
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>
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.
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.
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.
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",
1108 recognized arguments have their specified meanings,
1109 while the rest are used to override
1110 any same-named existing &consvars;
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,
1125 (<literal>-</literal>)
1126 to ignore the exit status of the external command.
1137 action="$FOO_BUILD < $SOURCES > $TARGET"
1143 action=["rm -f $TARGET", "$BAR_BUILD < $SOURCES > $TARGET"],
1144 ENV={'PATH': '/usr/local/bin/'},
1149 def rename(env, target, source):
1150 os.rename('.tmp', str(target[0]))
1156 action=["$BAZ_BUILD < $SOURCES > .tmp", rename],
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
1182 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
1184 env['DISTDIR'] = 'destination/directory'
1185 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
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.
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>
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.
1206 <varlistentry id="f-DebugOptions">
1207 <term><function>DebugOptions</function>(<parameter>[json]</parameter>)</term>
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.
1214 DebugOptions(json='#/build/output/scons_stats.json')
1216 <para><emphasis>New in version 4.6.0.</emphasis></para>
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>
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:
1234 <term><literal>"content"</literal></term>
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.
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.
1256 <term><literal>"content-timestamp"</literal></term>
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>
1267 This provides behavior very similar
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
1280 and runs the build again,
1281 all within a single second.
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.
1293 <term><literal>"timestamp-newer"</literal></term>
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>.
1307 <term><literal>"timestamp-match"</literal></term>
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.
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')
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:
1349 <term><parameter>dependency</parameter></term>
1352 The Node (file) which
1354 <parameter>target</parameter>
1356 if it has "changed" since the last time
1357 <parameter>target</parameter>
1363 <term><parameter>target</parameter></term>
1366 The Node (file) being built.
1368 this is what should get rebuilt
1370 <parameter>dependency</parameter>
1376 <term><parameter>prev_ni</parameter></term>
1379 Stored information about the state of the
1380 <parameter>dependency</parameter>
1382 <parameter>target</parameter>
1384 This can be consulted to match various
1385 file characteristics
1386 such as the timestamp,
1387 size, or &contentsig;.
1392 <term><parameter>repo_node</parameter></term>
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.
1412 <parameter>function</parameter>
1413 should return a value which evaluates
1414 <constant>True</constant>
1416 <parameter>dependency</parameter>
1417 has "changed" since the last time
1419 <parameter>target</parameter>
1421 (indicating that the target
1422 <emphasis>should</emphasis>
1424 and a value which evaluates
1425 <constant>False</constant>
1427 (indicating that the target should
1428 <emphasis>not</emphasis>
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.
1441 def my_decider(dependency, target, prev_ni, repo_node=None):
1442 return not os.path.exists(str(target))
1444 env.Decider(my_decider)
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>
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").
1460 <parameter>target</parameter> may be one or more 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;
1474 will add to the (now empty) default target list
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.
1486 The current list of targets added using
1487 &f-Default; is available in the
1488 &DEFAULT_TARGETS; list (see below).
1496 Default('foo', 'bar', 'baz')
1497 env.Default(['a', 'b', 'c'])
1498 hello = env.Program('hello', 'hello.c')
1504 <varlistentry id="f-DefaultEnvironment">
1505 <term><function>DefaultEnvironment</function>(<parameter>[key=value, ...]</parameter>)</term>
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;.
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.
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.
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.
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.
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>
1556 Specifies an explicit dependency;
1558 <parameter>target</parameter>
1561 <parameter>dependency</parameter>
1564 <parameter>target</parameter>
1566 <parameter>dependency</parameter>
1568 (usually the path name of a file or directory)
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
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)
1599 <varlistentry id="f-Detect">
1600 <term><replaceable>env</replaceable>.<methodname>Detect</methodname>(<parameter>progs</parameter>)</term>
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;.
1616 <varlistentry id="f-Dictionary">
1617 <term><replaceable>env</replaceable>.<methodname>Dictionary</methodname>(<parameter>[var, ...], [as_dict=]</parameter>)</term>
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.
1638 cvars = env.Dictionary()
1639 cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
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
1655 <emphasis>Changed in NEXT_RELEASE</emphasis>:
1656 <parameter>as_dict</parameter> added.
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>
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.
1672 <parameter>directory</parameter>
1673 is specified, the current script's directory is used as the parent.
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>.
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.
1698 <varlistentry id="f-Dump">
1699 <term><replaceable>env</replaceable>.<methodname>Dump</methodname>(<parameter>[var, ...], [format=TYPE]</parameter>)</term>
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.
1709 The optional <parameter>format</parameter> string
1710 selects the serialization format:
1714 <term><literal>pretty</literal></term>
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).
1725 <term><literal>json</literal></term>
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>..
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.
1746 Examples: this &SConstruct;
1751 print(env.Dump('CCCOM'))
1752 print(env.Dump('CC', 'CCFLAGS', format='json'))
1756 will print something like:
1760 {'CCCOM': '$CC -o $TARGET -c $CFLAGS $CCFLAGS $_CCCOMCOM $SOURCES'}
1768 While this &SConstruct;:
1777 will print something like:
1781 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
1784 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
1791 <varlistentry id="f-EnsurePythonVersion">
1792 <term><function>EnsurePythonVersion</function>(<parameter>major, minor</parameter>)</term>
1794 Ensure that the Python version is at least
1795 <varname>major</varname>.<varname>minor</varname>.
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.
1806 EnsurePythonVersion(2,2)
1810 <varlistentry id="f-EnsureSConsVersion">
1811 <term><function>EnsureSConsVersion</function>(<parameter>major, minor, [revision]</parameter>)</term>
1813 Ensure that the SCons version is at least
1814 <varname>major.minor</varname>,
1816 <varname>major.minor.revision</varname>.
1818 <varname>revision</varname>
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.
1830 EnsureSConsVersion(0,14)
1832 EnsureSConsVersion(0,96,90)
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>
1840 Return a new &consenv;
1841 initialized with the specified
1842 <parameter>key</parameter>=<replaceable>value</replaceable>
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
1852 See the manpage section "Construction Environments" for more details.
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>
1861 <parameter>action</parameter>
1862 may be an Action object
1863 or it may be a command-line string,
1865 or executable &Python; function,
1866 each of which will first be converted
1867 into an Action object
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:
1877 Execute(Copy('file.out', 'file.in'))
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.
1891 &f-Execute; returns the exit value of the command
1892 or return value of the &Python; function.
1894 prints an error message if the executed
1895 <parameter>action</parameter>
1896 fails (exits with or returns a non-zero value),
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
1903 you must explicitly check for a non-zero return value:
1907 if Execute("mkdir sub/dir/ectory"):
1908 # The mkdir failed, don't try to build.
1913 <varlistentry id="f-Exit">
1914 <term><function>Exit</function>(<parameter>[value]</parameter>)</term>
1920 <varname>value</varname>.
1921 A default exit value of
1922 <literal>0</literal>
1924 is used if no value is specified.
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>
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.
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.
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.
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.
1977 # Make env available for all SConscript files to Import().
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:
1990 # Make env available using the name debug:
1991 Export({"debug": env})
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.
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>
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.
2015 <parameter>directory</parameter>
2016 is specified, the current script's directory is used as the parent.
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>.
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.
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>
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.
2061 foo = env.FindFile('foo', ['dir1', 'dir2'])
2065 <varlistentry id="f-FindInstalledFiles">
2066 <term><function>FindInstalledFiles</function>()</term>
2067 <term><replaceable>env</replaceable>.<methodname>FindInstalledFiles</methodname>()</term>
2069 Returns the list of targets set up by the
2077 This function serves as a convenient method to select the contents of
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()
2100 <varlistentry id="f-FindPathDirs">
2101 <term><function>FindPathDirs</function>(<parameter>variable</parameter>)</term>
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
2122 is generally preferable to
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
2131 or in code repositories
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,
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',
2156 path_function = FindPathDirs('MYPATH'))
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>
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
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.
2174 This function is a convenient method to select the contents of a Source
2183 Program('src/main_a.c')
2184 Program('src/main_b.c')
2187 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
2190 # returns ['src/main_b.c', 'src/main_a.c' ]
2191 FindSourceFiles('src')
2195 As you can see, build support files (&SConstruct; in the above example)
2196 will also be returned by this function.
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>
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.
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):
2239 <varlistentry id="f-GetBuildFailures">
2240 <term><function>GetBuildFailures</function>()</term>
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>
2248 with the following attributes
2249 that record various aspects
2250 of the build failure:
2254 <literal>.node</literal>
2255 The node that was being built
2256 when the build failure occurred.
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
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.)
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>
2285 if an attempt to build a target named
2286 <filename>sub/dir/target</filename>
2288 <filename>sub/dir</filename>
2289 directory could not be created,
2291 <literal>.node</literal>
2293 <filename>sub/dir/target</filename>
2295 <literal>.filename</literal>
2297 <filename>sub/dir</filename>.
2301 <literal>.executor</literal>
2302 The SCons Executor object
2305 This can be used to retrieve
2306 the construction environment used
2307 for the failed action.
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.
2320 <literal>.command</literal>
2321 The actual expanded command that was executed and failed,
2325 and other construction variables.
2330 &f-GetBuildFailures;
2332 will always return an empty list
2333 until any build failure has occurred,
2335 &f-GetBuildFailures;
2336 will always return an empty list
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
2345 <function>atexit.register</function>()
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)
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>
2368 path name (or names) for the specified
2369 <parameter>file</parameter>
2372 <parameter>file</parameter>
2376 Nodes or strings representing path names.
2380 <varlistentry id="f-GetLaunchDir">
2381 <term><function>GetLaunchDir</function>()</term>
2383 Returns the absolute path name of the directory from which
2385 was initially invoked.
2386 This can be useful when using the
2387 <option>-u</option>,
2391 options, which internally
2392 change to the directory in which the
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>
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
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.
2421 <informaltable rowsep="1" colsep="1" frame="topbot">
2425 <entry align="left">Query name</entry>
2426 <entry align="left">Command-line options</entry>
2427 <entry align="left">Notes</entry>
2433 <entry><varname>cache_debug</varname></entry>
2434 <entry><option>--cache-debug</option></entry>
2437 <entry><varname>cache_disable</varname></entry>
2439 <option>--cache-disable</option>,
2440 <option>--no-cache</option>
2444 <entry><varname>cache_force</varname></entry>
2446 <option>--cache-force</option>,
2447 <option>--cache-populate</option>
2451 <entry><varname>cache_readonly</varname></entry>
2452 <entry><option>--cache-readonly</option></entry>
2455 <entry><varname>cache_show</varname></entry>
2456 <entry><option>--cache-show</option></entry>
2459 <entry><varname>clean</varname></entry>
2461 <option>-c</option>,
2462 <option>--clean</option>,
2463 <option>--remove</option>
2467 <entry><varname>climb_up</varname></entry>
2472 <option>--up</option>
2473 <option>--search_up</option>
2477 <entry><varname>config</varname></entry>
2478 <entry><option>--config</option></entry>
2481 <entry><varname>debug</varname></entry>
2482 <entry><option>--debug</option></entry>
2485 <entry><varname>directory</varname></entry>
2486 <entry><option>-C</option>, <option>--directory</option></entry>
2489 <entry><varname>diskcheck</varname></entry>
2490 <entry><option>--diskcheck</option></entry>
2493 <entry><varname>duplicate</varname></entry>
2494 <entry><option>--duplicate</option></entry>
2497 <entry><varname>enable_virtualenv</varname></entry>
2498 <entry><option>--enable-virtualenv</option></entry>
2501 <entry><varname>experimental</varname></entry>
2502 <entry><option>--experimental</option></entry>
2503 <entry><emphasis>since 4.2</emphasis></entry>
2506 <entry><varname>file</varname></entry>
2508 <option>-f</option>,
2509 <option>--file</option>,
2510 <option>--makefile</option>,
2511 <option>--sconstruct</option>
2515 <entry><varname>hash_format</varname></entry>
2516 <entry><option>--hash-format</option></entry>
2517 <entry><emphasis>since 4.2</emphasis></entry>
2520 <entry><varname>help</varname></entry>
2521 <entry><option>-h</option>, <option>--help</option></entry>
2524 <entry><varname>ignore_errors</varname></entry>
2525 <entry><option>-i</option>, <option>--ignore-errors</option></entry>
2528 <entry><varname>ignore_virtualenv</varname></entry>
2529 <entry><option>--ignore-virtualenv</option></entry>
2532 <entry><varname>implicit_cache</varname></entry>
2533 <entry><option>--implicit-cache</option></entry>
2536 <entry><varname>implicit_deps_changed</varname></entry>
2537 <entry><option>--implicit-deps-changed</option></entry>
2540 <entry><varname>implicit_deps_unchanged</varname></entry>
2541 <entry><option>--implicit-deps-unchanged</option></entry>
2544 <entry><varname>include_dir</varname></entry>
2545 <entry><option>-I</option>, <option>--include-dir</option></entry>
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>
2553 <entry><varname>keep_going</varname></entry>
2554 <entry><option>-k</option>, <option>--keep-going</option></entry>
2557 <entry><varname>max_drift</varname></entry>
2558 <entry><option>--max-drift</option></entry>
2561 <entry><varname>md5_chunksize</varname></entry>
2563 <option>--hash-chunksize</option>,
2564 <option>--md5-chunksize</option>
2566 <entry><emphasis><option>--hash-chunksize</option> since 4.2</emphasis></entry>
2569 <entry><varname>no_exec</varname></entry>
2571 <option>-n</option>,
2572 <option>--no-exec</option>,
2573 <option>--just-print</option>,
2574 <option>--dry-run</option>,
2575 <option>--recon</option>
2579 <entry><varname>no_progress</varname></entry>
2580 <entry><option>-Q</option></entry>
2583 <entry><varname>num_jobs</varname></entry>
2584 <entry><option>-j</option>, <option>--jobs</option></entry>
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>
2592 <entry><varname>profile_file</varname></entry>
2593 <entry><option>--profile</option></entry>
2596 <entry><varname>question</varname></entry>
2597 <entry><option>-q</option>, <option>--question</option></entry>
2600 <entry><varname>random</varname></entry>
2601 <entry><option>--random</option></entry>
2604 <entry><varname>repository</varname></entry>
2606 <option>-Y</option>,
2607 <option>--repository</option>,
2608 <option>--srcdir</option>
2612 <entry><varname>silent</varname></entry>
2614 <option>-s</option>,
2615 <option>--silent</option>,
2616 <option>--quiet</option>
2620 <entry><varname>site_dir</varname></entry>
2621 <entry><option>--site-dir</option>, <option>--no-site-dir</option></entry>
2624 <entry><varname>stack_size</varname></entry>
2625 <entry><option>--stack-size</option></entry>
2628 <entry><varname>taskmastertrace_file</varname></entry>
2629 <entry><option>--taskmastertrace</option></entry>
2632 <entry><varname>tree_printers</varname></entry>
2633 <entry><option>--tree</option></entry>
2636 <entry><varname>warn</varname></entry>
2637 <entry><option>--warn</option>, <option>--warning</option></entry>
2645 <varlistentry id="f-GetSConsVersion">
2646 <term><function>GetSConsVersion</function>()</term>
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>.
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>
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,
2662 or (most commonly) relative to the directory of the current
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.
2677 <parameter>pattern</parameter>
2678 can contain POSIX-style shell metacharacters for matching:
2681 <informaltable rowsep="1" colsep="1" frame="topbot">
2685 <entry>Pattern</entry>
2686 <entry>Meaning</entry>
2691 <entry><literal>*</literal></entry>
2692 <entry>matches everything</entry>
2695 <entry><literal>?</literal></entry>
2696 <entry>matches any single character</entry>
2699 <entry><literal>[seq]</literal></entry>
2700 <entry>matches any character in <emphasis>seq</emphasis>
2701 (can be a list or a range).</entry>
2704 <entry><literal>[!seq]</literal></entry>
2705 <entry>matches any character not in <emphasis>seq</emphasis></entry>
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>.
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.
2728 understands repositories
2732 and source directories
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.
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.
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? -->
2767 <parameter>strings</parameter>
2768 argument evaluates true,
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
2780 any Node translation there will be relative
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>.
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)
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>
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>
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.
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.
2846 <emphasis>Changed in 4.6.0</emphasis>: added <parameter>local_only</parameter>.
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>
2855 Ignores <parameter>dependency</parameter>
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.
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.
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')
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>
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
2904 Multiple variable names can be passed to
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.
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;.
2925 Import("env", "variable")
2926 Import(["env", "variable"])
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>
2936 <parameter>string</parameter>
2937 will be preserved as-is
2938 and not have &consvars; expanded.
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>
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.
2955 <varlistentry id="f-MergeFlags">
2956 <term><replaceable>env</replaceable>.<methodname>MergeFlags</methodname>(<parameter>arg, [unique]</parameter>)</term>
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
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.
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.
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.
3011 '!pkg-config gtk+-2.0 --cflags --libs',
3012 '!pkg-config libpng12 --cflags --libs',
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>
3022 Specifies a list of files which should
3023 <emphasis>not</emphasis>
3024 be cached whenever the
3026 method has been activated.
3027 The specified targets may be a list
3028 or an individual target.
3032 Multiple files should be specified
3033 either as separate arguments to the
3035 method, or as a list.
3037 will also accept the return value of any of the &consenv;
3044 on directories and other non-File Node types has no effect because
3045 only File Nodes are cached.
3054 NoCache(env.Program('hello', 'hello.c'))
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>
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
3067 command line option.
3068 The specified targets may be a list
3069 or an individual target.
3073 and prevent each specified target
3074 from being removed by calls to the
3080 Multiple files or directories should be specified
3081 either as separate arguments to the
3083 method, or as a list.
3085 will also accept the return value of any of the &consenv;
3092 for a target overrides calling
3094 for the same target,
3095 and any targets passed to both functions will
3096 <emphasis>not</emphasis>
3108 NoClean(env.Program('hello', 'hello.c'))
3112 <varlistentry id="f-ParseConfig">
3113 <term><replaceable>env</replaceable>.<methodname>ParseConfig</methodname>(<parameter>command, [function, unique]</parameter>)</term>
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
3121 If <parameter>function</parameter>
3122 is omitted or <constant>None</constant>,
3123 &f-link-env-MergeFlags; is used.
3125 duplicate values are not
3126 added to any &consvars;;
3128 <parameter>unique=False</parameter>
3129 to allow duplicate values to be added.
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.
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>,
3160 <parameter>unique</parameter> flag.
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>
3168 Parses the contents of <parameter>filename</parameter>
3169 as a list of dependencies in the style of
3172 <application>mkdep</application>,
3173 and explicitly establishes all of the listed dependencies.
3179 if <parameter>filename</parameter>
3182 <parameter>must_exist</parameter>
3183 argument may be set to <constant>True</constant>
3185 raise an exception if the file does not exist,
3186 or is otherwise inaccessible.
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>
3201 which should typically only
3202 write dependency information for
3203 one output file into a corresponding
3204 <filename>.d</filename>
3209 <parameter>filename</parameter>
3210 and all of the files listed therein
3211 will be interpreted relative to
3212 the directory of the
3214 file which calls the
3220 <varlistentry id="f-ParseFlags">
3221 <term><replaceable>env</replaceable>.<methodname>ParseFlags</methodname>(<parameter>flags, ...</parameter>)</term>
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;.
3234 will call this method if its argument is not a dictionary,
3235 so it is usually not necessary to call
3237 directly unless you want to manipulate the values.)
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
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.
3259 Flag values are translated according to the prefix found,
3260 and added to the following &consvars;:
3264 -arch CCFLAGS, LINKFLAGS
3266 -framework FRAMEWORKS
3267 -frameworkdir= FRAMEWORKPATH
3268 -fmerge-all-constants CCFLAGS, LINKFLAGS
3269 -fopenmp CCFLAGS, LINKFLAGS
3270 -fsanitize CCFLAGS, LINKFLAGS
3273 -isysroot CCFLAGS, LINKFLAGS
3280 -mno-cygwin CCFLAGS, LINKFLAGS
3282 -openmp CCFLAGS, LINKFLAGS
3283 -pthread CCFLAGS, LINKFLAGS
3286 -Wa, ASFLAGS, CCFLAGS
3293 + CCFLAGS, LINKFLAGS
3297 Any other strings not associated with options
3298 are assumed to be the names of libraries
3300 &cv-LIBS; &consvar;.
3304 Examples (all of which produce the same result):
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')
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>
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
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.
3335 env = Environment(platform=Platform('win32'))
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.
3346 env.Platform('posix')
3350 See the manpage section "Construction Environments" for more details.
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>
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.
3367 <varlistentry id="f-Prepend">
3368 <term><replaceable>env</replaceable>.<methodname>Prepend</methodname>(<parameter>key=val, [...]</parameter>)</term>
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;
3381 env.Prepend(CCFLAGS='-g ', FOO=['foo.yyy'])
3385 See also &f-link-env-Append;,
3386 &f-link-env-AppendUnique;
3387 and &f-link-env-PrependUnique;.
3391 <varlistentry id="f-PrependENVPath">
3392 <term><replaceable>env</replaceable>.<methodname>PrependENVPath</methodname>(<parameter>name, newpath, [envname, sep, delete_existing=True]</parameter>)</term>
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>).
3421 print('before:', env['ENV']['INCLUDE'])
3422 include_path = '/foo/bar:/foo'
3423 env.PrependENVPath('INCLUDE', include_path)
3424 print('after:', env['ENV']['INCLUDE'])
3427 <para>Yields:</para>
3431 after: /foo/bar:/foo:/biz
3435 See also &f-link-env-AppendENVPath;.
3440 <varlistentry id="f-PrependUnique">
3441 <term><replaceable>env</replaceable>.<methodname>PrependUnique</methodname>(<parameter>key=val, [...], [delete_existing=False]</parameter>)</term>
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
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.
3462 env.PrependUnique(CCFLAGS='-g', FOO=['foo.yyy'])
3466 See also &f-link-env-Append;,
3467 &f-link-env-AppendUnique;
3468 and &f-link-env-Prepend;.
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>
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).
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
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.)
3504 An example of a simple custom progress function
3505 that prints a string containing the Node name
3510 def my_progress_function(node, *args, **kwargs):
3511 print('Evaluating node %s!' % node)
3512 Progress(my_progress_function, interval=10)
3516 A more complicated example of a custom progress display object
3517 that prints a string containing a count
3518 every 100 evaluated Nodes.
3520 <literal>\r</literal>
3522 at the end so that the string
3523 will overwrite itself on a display:
3528 class ProgressCounter(object):
3530 def __call__(self, node, *args, **kw):
3532 sys.stderr.write('Evaluated %s nodes\r' % self.count)
3534 Progress(ProgressCounter(), interval=100)
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>
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>
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.
3560 The following will print a series of dots
3561 on the error output,
3562 one dot for every 100 evaluated Nodes:
3567 Progress('.', interval=100, file=sys.stderr)
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,
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:
3593 Progress('$TARGET\r', overwrite=True)
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:
3603 Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
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>
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.
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.
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>
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.
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
3652 &f-link-Environment;
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.
3667 tools=["default", "ExampleTool"],
3668 toolpath=[PyPackageDir("example_tool")]
3673 <varlistentry id="f-Replace">
3674 <term><replaceable>env</replaceable>.<methodname>Replace</methodname>(<parameter>key=val, [...]</parameter>)</term>
3676 Replaces &consvars; in the Environment
3677 with the specified keyword arguments.
3685 env.Replace(CCFLAGS='-g', FOO='foo.xxx')
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>
3694 <parameter>directory</parameter>
3695 as a repository to be searched for files contributing to the build.
3699 with repositories searched in the given order.
3700 Repositories specified via command-line option
3701 have higher priority.
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
3718 allowing better decisions on whether they are
3723 Note that if an up-to-date derived file
3724 already exists in a repository,
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.
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>
3737 Specifies an order-only relationship
3738 between <parameter>target</parameter>
3739 and <parameter>prerequisite</parameter>.
3741 will be (re)built, if necessary,
3742 <emphasis>before</emphasis>
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.
3762 env.Requires('foo', 'file-that-must-be-built-before-foo')
3766 <varlistentry id="f-Return">
3767 <term><function>Return</function>(<parameter>[vars..., stop=True]</parameter>)</term>
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>
3782 By default &Return; stops processing the current SConscript
3783 and returns immediately.
3785 <literal>stop</literal>
3787 may be set to a false value
3788 to continue processing the rest of the SConscript
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>
3805 # Returns no values (evaluates False)
3808 # Returns the value of the 'foo' Python variable.
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'.
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>
3823 Creates a Scanner object for
3825 <parameter>function</parameter>.
3826 See manpage section "Scanner Objects"
3827 for a complete explanation of the arguments and behavior.
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>
3837 Executes subsidiary SConscript (build configuration) file(s).
3838 There are two ways to call the
3839 &f-SConscript; function.
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).
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')
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.
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
3873 by supplying an optional
3874 <varname>name</varname>=<replaceable>scriptname</replaceable>
3876 The first three examples below have the same effect
3877 as the first three examples above:
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')
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
3907 <!-- If multiple dirs are provided, each script gets a fresh export. -->
3908 The subsidiary SConscript files
3911 function to import the variables into their local scope.
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')
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>
3938 SConscript('src/SConscript', variant_dir='build')
3946 VariantDir('build', 'src')
3947 SConscript('build/SConscript')
3951 If the sources are in the same directory as the
3956 SConscript('SConscript', variant_dir='build')
3964 VariantDir('build', '.')
3965 SConscript('build/SConscript')
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
3976 for additional details and restrictions.
3982 <varname>variant_dir</varname>
3984 <varname>src_dir</varname>
3986 xxxxx everything is in a state of confusion.
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.
4007 and what about this alternative?
4008 TODO??? SConscript('build/SConscript', src_dir='src')
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),
4021 <literal>must_exist=False</literal> in the &f-SConscript; call.
4025 <emphasis>Changed in 4.6.0</emphasis>: <parameter>must_exist</parameter>
4026 now defaults to <constant>True</constant>.
4030 Here are some composite examples:
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')
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)
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)
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)
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>.
4076 <varlistentry id="f-SConscriptChdir">
4077 <term><function>SConscriptChdir</function>(<parameter>value</parameter>)</term>
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
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
4105 SConscriptChdir(False)
4106 SConscript('foo/SConscript') # will not chdir to foo
4107 SConscriptChdir(True)
4108 SConscript('bar/SConscript') # will chdir to bar
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>
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.
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.
4128 <filename>.sconsign</filename>.
4129 The actual database file(s) stored on disk
4130 may have an appropriate suffix appended
4132 <parameter>dbm_module</parameter>
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.
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.
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.
4168 <parameter>name</parameter>
4170 <constant>None</constant>,
4172 will store file signatures
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.
4189 # Explicitly stores signatures in ".sconsign.dblite"
4190 # in the top-level SConstruct directory (the default behavior).
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.
4206 # Stores signatures in a GNU dbm format .sconsign file
4208 SConsignFile(dbm_module=dbm.gnu)
4212 <varlistentry id="f-SetDefault">
4213 <term><replaceable>env</replaceable>.<methodname>SetDefault</methodname>(<parameter>key=val, [...]</parameter>)</term>
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:
4221 env.SetDefault(FOO='foo')
4222 if 'FOO' not in env:
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>
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.
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>).
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.
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.
4274 The settable variables with their associated command-line options are:
4277 <informaltable rowsep="1" colsep="1" frame="topbot">
4281 <entry align="left">Settable name</entry>
4282 <entry align="left">Command-line options</entry>
4283 <entry align="left">Notes</entry>
4289 <entry><varname>clean</varname></entry>
4291 <option>-c</option>,
4292 <option>--clean</option>,
4293 <option>--remove</option>
4298 <entry><varname>diskcheck</varname></entry>
4299 <entry><option>--diskcheck</option></entry>
4303 <entry><varname>duplicate</varname></entry>
4304 <entry><option>--duplicate</option></entry>
4308 <entry><varname>experimental</varname></entry>
4309 <entry><option>--experimental</option></entry>
4310 <entry><emphasis>since 4.2</emphasis></entry>
4314 <entry><varname>hash_chunksize</varname></entry>
4315 <entry><option>--hash-chunksize</option></entry>
4317 Actually sets <varname>md5_chunksize</varname>.
4318 <emphasis>since 4.2</emphasis>
4323 <entry><varname>hash_format</varname></entry>
4324 <entry><option>--hash-format</option></entry>
4325 <entry><emphasis>since 4.2</emphasis></entry>
4329 <entry><varname>help</varname></entry>
4330 <entry><option>-h</option>, <option>--help</option></entry>
4334 <entry><varname>implicit_cache</varname></entry>
4335 <entry><option>--implicit-cache</option></entry>
4339 <entry><varname>implicit_deps_changed</varname></entry>
4340 <entry><option>--implicit-deps-changed</option></entry>
4342 Also sets <varname>implicit_cache</varname>.
4343 <emphasis>(settable since 4.2)</emphasis>
4348 <entry><varname>implicit_deps_unchanged</varname></entry>
4349 <entry><option>--implicit-deps-unchanged</option></entry>
4351 Also sets <varname>implicit_cache</varname>.
4352 <emphasis>(settable since 4.2)</emphasis>
4357 <entry><varname>max_drift</varname></entry>
4358 <entry><option>--max-drift</option></entry>
4362 <entry><varname>md5_chunksize</varname></entry>
4363 <entry><option>--md5-chunksize</option></entry>
4367 <entry><varname>no_exec</varname></entry>
4369 <option>-n</option>,
4370 <option>--no-exec</option>,
4371 <option>--just-print</option>,
4372 <option>--dry-run</option>,
4373 <option>--recon</option>
4378 <entry><varname>no_progress</varname></entry>
4379 <entry><option>-Q</option></entry>
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
4395 <entry><varname>num_jobs</varname></entry>
4396 <entry><option>-j</option>, <option>--jobs</option></entry>
4400 <entry><varname>random</varname></entry>
4401 <entry><option>--random</option></entry>
4405 <entry><varname>silent</varname></entry>
4407 <option>-s</option>,
4408 <option>--silent</option>,
4409 <option>--quiet</option>
4414 <entry><varname>stack_size</varname></entry>
4415 <entry><option>--stack-size</option></entry>
4419 <entry><varname>warn</varname></entry>
4420 <entry><option>--warn</option></entry>
4432 SetOption('max_drift', 0)
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>
4441 <parameter>side_effect</parameter>
4442 as a side effect of building
4443 <parameter>target</parameter>.
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,
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.
4466 Because multiple build commands may update
4467 the same side effect file,
4469 <parameter>side_effect</parameter>
4471 <emphasis>not</emphasis>
4472 automatically removed
4474 <parameter>target</parameter>
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>
4487 you must specify this explicitly
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.
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>
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.
4527 files = Split("f1.c f2.c f3.c")
4528 files = env.Split("f4.c f5.c f6.c")
4537 <varlistentry id="f-subst">
4538 <term><replaceable>env</replaceable>.<methodname>subst</methodname>(<parameter>input, [raw, target, source, conv]</parameter>)</term>
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>.
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.
4559 <literal>$(</literal>
4561 <literal>$)</literal>
4562 character sequences will be stripped from the returned string,
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>
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>
4580 (as is done for signature calculation).
4584 If <parameter>input</parameter> is a sequence
4586 the individual elements of
4587 the sequence will be expanded,
4588 and the results will be returned as a list.
4593 <parameter>target</parameter>
4595 <parameter>source</parameter>
4597 must be set to lists of
4598 target and source nodes, respectively,
4605 to be available for expansion.
4606 This is usually necessary if you are
4609 from within a &Python; function used
4614 Returned string values or sequence elements
4615 are converted to their string representation by default.
4617 <parameter>conv</parameter>
4619 may specify a conversion function
4620 that will be used in place of
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.
4635 print(env.subst("The C compiler is: $CC"))
4637 def compile(target, source, env):
4638 sourceDir = env.subst(
4644 source_nodes = env.subst('$EXPAND_TO_NODELIST', conv=lambda x: x)
4648 <varlistentry id="f-Tag">
4649 <term><function>Tag</function>(<parameter>node, tags</parameter>)</term>
4651 Annotates file or directory Nodes with
4652 information about how the
4654 Builder should package those files or directories.
4655 All Node-level tags are optional.
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)
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>
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.
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
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,
4703 Any remaining keyword arguments are saved in
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
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>).
4728 env.Tool('opengl', toolpath=['build/tools'])
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;.
4748 env = Environment(tools=[Tool('msvc')])
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
4758 <varlistentry id="f-ValidateOptions">
4759 <term><function>ValidateOptions</function>(<parameter>[throw_exception=False]</parameter>)</term>
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.
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;.
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).
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:
4795 $ <userinput>scons --compilers=mingw</userinput> # the correct flag is --compiler
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:
4806 <programlisting language="python">
4807 from SCons.Script.SConsOptions import SConsBadOptionError
4817 # ... other SConscript logic ...
4820 ValidateOptions(throw_exception=True)
4821 except SConsBadOptionError as e:
4822 print(f"ValidateOptions detects a fail: ", e.opt_str)
4826 <para><emphasis>New in version 4.5.0</emphasis></para>
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>
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.
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."
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.
4861 <methodname>write</methodname>
4862 method that can be used to "build" a Value Node
4863 by setting a new value.
4865 <methodname>read</methodname>
4866 method returns the built value of the Node.
4870 <emphasis>Changed in version 4.0:</emphasis>
4871 the <parameter>name</parameter> parameter was added.
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.
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.
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))
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>
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.
4926 can be called multiple times with the same
4927 <parameter>src_dir</parameter>
4928 to set up multiple variant builds with different options.
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.
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.
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.
4962 Duplicating the source files may be disabled by setting the
4963 <parameter>duplicate</parameter>
4965 <constant>False</constant>.
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.
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:
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})
5005 &f-link-SConscript; function
5006 for another way to specify a variant directory
5007 in conjunction with calling a subsidiary SConscript file.
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)
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>
5033 Searches for the specified executable
5034 <parameter>program</parameter>,
5035 returning the full path to the program
5036 or <constant>None</constant>.
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>
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>
5065 When called as a global function, uses the external
5067 <literal>os.environ['PATH']</literal>
5069 <literal>os.environ['PATHEXT']</literal>,
5071 <parameter>path</parameter> and
5072 <parameter>pathext</parameter> are
5073 <constant>None</constant>.
5079 <parameter>reject</parameter>