diff options
Diffstat (limited to 'doc/generated/functions.gen')
| -rw-r--r-- | doc/generated/functions.gen | 5120 |
1 files changed, 5120 insertions, 0 deletions
diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen new file mode 100644 index 0000000..072b91c --- /dev/null +++ b/doc/generated/functions.gen @@ -0,0 +1,5120 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + <!ENTITY % builders-mod SYSTEM "builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "variables.mod"> + %variables-mod; +]> + +<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/scons.xsd scons.xsd"> + <varlistentry id="f-Action"> + <term> + <literal>Action(action, [cmd/str/fun, [var, ...]] [option=value, ...])</literal> + </term> + <term> + <literal>env.Action(action, [cmd/str/fun, [var, ...]] [option=value, ...])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Creates an Action object for +the specified +<varname>action</varname>. +See the section "Action Objects," +below, for a complete explanation of the arguments and behavior. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that the +<function>env.Action</function>() +form of the invocation will expand +construction variables in any argument strings, +including the +<varname>action</varname> +argument, at the time it is called +using the construction variables in the +<varname>env</varname> +construction environment through which +<function>env.Action</function>() +was called. +The +<function>Action</function>() +form delays all variable expansion +until the Action object is actually used. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-AddMethod"> + <term> + <literal>AddMethod(object, function, [name])</literal> + </term> + <term> + <literal>env.AddMethod(function, [name])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +When called with the +<function>AddMethod</function>() +form, +adds the specified +<varname>function</varname> +to the specified +<varname>object</varname> +as the specified method +<varname>name</varname>. +When called with the +<function>env.AddMethod</function>() +form, +adds the specified +<varname>function</varname> +to the construction environment +<varname>env</varname> +as the specified method +<varname>name</varname>. +In both cases, if +<varname>name</varname> +is omitted or +<literal>None</literal>, +the name of the +specified +<varname>function</varname> +itself is used for the method name. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# Note that the first argument to the function to +# be attached as a method must be the object through +# which the method will be called; the Python +# convention is to call it 'self'. +def my_method(self, arg): + print "my_method() got", arg + +# Use the global AddMethod() function to add a method +# to the Environment class. This +AddMethod(Environment, my_method) +env = Environment() +env.my_method('arg') + +# Add the function as a method, using the function +# name for the method call. +env = Environment() +env.AddMethod(my_method, 'other_method_name') +env.other_method_name('another arg') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-AddOption"> + <term> + <literal>AddOption(arguments)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This function adds a new command-line option to be recognized. +The specified +<varname>arguments</varname> +are the same as supported by the standard Python +<function>optparse.add_option</function>() +method (with a few additional capabilities noted below); +see the documentation for +<literal>optparse</literal> +for a thorough discussion of its option-processing capabities. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +In addition to the arguments and values supported by the +<function>optparse.add_option</function>() +method, +the SCons +<function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function> +function allows you to set the +<literal>nargs</literal> +keyword value to +<literal>'?'</literal> +(a string with just the question mark) +to indicate that the specified long option(s) take(s) an +<emphasis>optional</emphasis> +argument. +When +<literal>nargs = '?'</literal> +is passed to the +<function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function> +function, the +<literal>const</literal> +keyword argument +may be used to supply the "default" +value that should be used when the +option is specified on the command line +without an explicit argument. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If no +<literal>default=</literal> +keyword argument is supplied when calling +<function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function>, +the option will have a default value of +<literal>None</literal>. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Once a new command-line option has been added with +<function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function>, +the option value may be accessed using +<function xmlns="http://www.scons.org/dbxsd/v1.0">GetOption</function> +or +<function>env.GetOption</function>(). +The value may also be set, using +<function xmlns="http://www.scons.org/dbxsd/v1.0">SetOption</function> +or +<function>env.SetOption</function>(), +if conditions in a +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename> +require overriding any default value. +Note, however, that a +value specified on the command line will +<emphasis>always</emphasis> +override a value set by any SConscript file. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Any specified +<literal>help=</literal> +strings for the new option(s) +will be displayed by the +<option>-H</option> +or +<option>-h</option> +options +(the latter only if no other help text is +specified in the SConscript files). +The help text for the local options specified by +<function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function> +will appear below the SCons options themselves, +under a separate +<literal>Local Options</literal> +heading. +The options will appear in the help text +in the order in which the +<function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function> +calls occur. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +AddOption('--prefix', + dest='prefix', + nargs=1, type='string', + action='store', + metavar='DIR', + help='installation prefix') +env = Environment(PREFIX = GetOption('prefix')) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-AddPostAction"> + <term> + <literal>AddPostAction(target, action)</literal> + </term> + <term> + <literal>env.AddPostAction(target, action)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Arranges for the specified +<varname>action</varname> +to be performed +after the specified +<varname>target</varname> +has been built. +The specified action(s) may be +an Action object, or anything that +can be converted into an Action object +(see below). +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +When multiple targets are supplied, +the action may be called multiple times, +once after each action that generates +one or more targets in the list. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-AddPreAction"> + <term> + <literal>AddPreAction(target, action)</literal> + </term> + <term> + <literal>env.AddPreAction(target, action)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Arranges for the specified +<varname>action</varname> +to be performed +before the specified +<varname>target</varname> +is built. +The specified action(s) may be +an Action object, or anything that +can be converted into an Action object +(see below). +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +When multiple targets are specified, +the action(s) may be called multiple times, +once before each action that generates +one or more targets in the list. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that if any of the targets are built in multiple steps, +the action will be invoked just +before the "final" action that specifically +generates the specified target(s). +For example, when building an executable program +from a specified source +<filename>.c</filename> +file via an intermediate object file: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +foo = Program('foo.c') +AddPreAction(foo, 'pre_action') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The specified +<literal>pre_action</literal> +would be executed before +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +calls the link command that actually +generates the executable program binary +<filename>foo</filename>, +not before compiling the +<filename>foo.c</filename> +file into an object file. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Alias"> + <term> + <literal>Alias(alias, [targets, [action]])</literal> + </term> + <term> + <literal>env.Alias(alias, [targets, [action]])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Creates one or more phony targets that +expand to one or more other targets. +An optional +<varname>action</varname> +(command) +or list of actions +can be specified that will be executed +whenever the any of the alias targets are out-of-date. +Returns the Node object representing the alias, +which exists outside of any file system. +This Node object, or the alias name, +may be used as a dependency of any other target, +including another alias. +<function xmlns="http://www.scons.org/dbxsd/v1.0">Alias</function> +can be called multiple times for the same +alias to add additional targets to the alias, +or additional actions to the list for this alias. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +Alias('install') +Alias('install', '/usr/bin') +Alias(['install', 'install-lib'], '/usr/local/lib') + +env.Alias('install', ['/usr/local/bin', '/usr/local/lib']) +env.Alias('install', ['/usr/local/man']) + +env.Alias('update', ['file1', 'file2'], "update_database $SOURCES") +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-AllowSubstExceptions"> + <term> + <literal>AllowSubstExceptions([exception, ...])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Specifies the exceptions that will be allowed +when expanding construction variables. +By default, +any construction variable expansions that generate a +<literal>NameError</literal> +or +<literal>IndexError</literal> +exception will expand to a +<literal>''</literal> +(a null string) and not cause scons to fail. +All exceptions not in the specified list +will generate an error message +and terminate processing. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If +<function xmlns="http://www.scons.org/dbxsd/v1.0">AllowSubstExceptions</function> +is called multiple times, +each call completely overwrites the previous list +of allowed exceptions. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# Requires that all construction variable names exist. +# (You may wish to do this if you want to enforce strictly +# that all construction variables must be defined before use.) +AllowSubstExceptions() + +# Also allow a string containing a zero-division expansion +# like '${1 / 0}' to evalute to ''. +AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-AlwaysBuild"> + <term> + <literal>AlwaysBuild(target, ...)</literal> + </term> + <term> + <literal>env.AlwaysBuild(target, ...)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Marks each given +<varname>target</varname> +so that it is always assumed to be out of date, +and will always be rebuilt if needed. +Note, however, that +<function xmlns="http://www.scons.org/dbxsd/v1.0">AlwaysBuild</function> +does not add its target(s) to the default target list, +so the targets will only be built +if they are specified on the command line, +or are a dependent of a target specified on the command line--but +they will +<emphasis>always</emphasis> +be built if so specified. +Multiple targets can be passed in to a single call to +<function xmlns="http://www.scons.org/dbxsd/v1.0">AlwaysBuild</function>. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Append"> + <term> + <literal>env.Append(key=val, [...])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Appends the specified keyword arguments +to the end of construction variables in the environment. +If the Environment does not have +the specified construction variable, +it is simply added to the environment. +If the values of the construction variable +and the keyword argument are the same type, +then the two values will be simply added together. +Otherwise, the construction variable +and the value of the keyword argument +are both coerced to lists, +and the lists are added together. +(See also the Prepend method, below.) +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy']) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-AppendENVPath"> + <term> + <literal>env.AppendENVPath(name, newpath, [envname, sep, delete_existing])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This appends new path elements to the given path in the +specified external environment +(<literal>ENV</literal> +by default). +This will only add +any particular path once (leaving the last one it encounters and +ignoring the rest, to preserve path order), +and to help assure this, +will normalize all paths (using +<function>os.path.normpath</function> +and +<function>os.path.normcase</function>). +This can also handle the +case where the given old path variable is a list instead of a +string, in which case a list will be returned instead of a string. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If +<varname>delete_existing</varname> +is 0, then adding a path that already exists +will not move it to the end; it will stay where it is in the list. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +print 'before:',env['ENV']['INCLUDE'] +include_path = '/foo/bar:/foo' +env.AppendENVPath('INCLUDE', include_path) +print 'after:',env['ENV']['INCLUDE'] + +yields: +before: /foo:/biz +after: /biz:/foo/bar:/foo +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-AppendUnique"> + <term> + <literal>env.AppendUnique(key=val, [...], delete_existing=0)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Appends the specified keyword arguments +to the end of construction variables in the environment. +If the Environment does not have +the specified construction variable, +it is simply added to the environment. +If the construction variable being appended to is a list, +then any value(s) that already exist in the +construction variable will +<emphasis>not</emphasis> +be added again to the list. +However, if delete_existing is 1, +existing matching values are removed first, so +existing values in the arg list move to the end of the list. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-BitKeeper"> + <term> + <literal>env.BitKeeper()</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +A factory function that +returns a Builder object +to be used to fetch source files +using BitKeeper. +The returned Builder +is intended to be passed to the +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function> +function. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This function is deprecated. For details, see the entry for the +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function> +function. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.SourceCode('.', env.BitKeeper()) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-BuildDir"> + <term> + <literal>BuildDir(build_dir, src_dir, [duplicate])</literal> + </term> + <term> + <literal>env.BuildDir(build_dir, src_dir, [duplicate])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Deprecated synonyms for +<function xmlns="http://www.scons.org/dbxsd/v1.0">VariantDir</function> +and +<function>env.VariantDir</function>(). +The +<varname>build_dir</varname> +argument becomes the +<varname>variant_dir</varname> +argument of +<function xmlns="http://www.scons.org/dbxsd/v1.0">VariantDir</function> +or +<function>env.VariantDir</function>(). +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Builder"> + <term> + <literal>Builder(action, [arguments])</literal> + </term> + <term> + <literal>env.Builder(action, [arguments])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Creates a Builder object for +the specified +<varname>action</varname>. +See the section "Builder Objects," +below, for a complete explanation of the arguments and behavior. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that the +<function>env.Builder</function>() +form of the invocation will expand +construction variables in any arguments strings, +including the +<varname>action</varname> +argument, +at the time it is called +using the construction variables in the +<varname>env</varname> +construction environment through which +<function>env.Builder</function>() +was called. +The +<function xmlns="http://www.scons.org/dbxsd/v1.0">Builder</function> +form delays all variable expansion +until after the Builder object is actually called. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-CacheDir"> + <term> + <literal>CacheDir(cache_dir)</literal> + </term> + <term> + <literal>env.CacheDir(cache_dir)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Specifies that +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will maintain a cache of derived files in +<varname>cache_dir</varname>. +The derived files in the cache will be shared +among all the builds using the same +<function xmlns="http://www.scons.org/dbxsd/v1.0">CacheDir</function> +call. +Specifying a +<varname>cache_dir</varname> +of +<literal>None</literal> +disables derived file caching. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Calling +<function>env.CacheDir</function>() +will only affect targets built +through the specified construction environment. +Calling +<function xmlns="http://www.scons.org/dbxsd/v1.0">CacheDir</function> +sets a global default +that will be used by all targets built +through construction environments +that do +<emphasis>not</emphasis> +have an +<function>env.CacheDir</function>() +specified. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +When a +<function>CacheDir</function>() +is being used and +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +finds a derived file that needs to be rebuilt, +it will first look in the cache to see if a +derived file has already been built +from identical input files and an identical build action +(as incorporated into the MD5 build signature). +If so, +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will retrieve the file from the cache. +If the derived file is not present in the cache, +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will rebuild it and +then place a copy of the built file in the cache +(identified by its MD5 build signature), +so that it may be retrieved by other +builds that need to build the same derived file +from identical inputs. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Use of a specified +<function xmlns="http://www.scons.org/dbxsd/v1.0">CacheDir</function> +may be disabled for any invocation +by using the +<option>--cache-disable</option> +option. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the +<option>--cache-force</option> +option is used, +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will place a copy of +<emphasis>all</emphasis> +derived files in the cache, +even if they already existed +and were not built by this invocation. +This is useful to populate a cache +the first time +<function xmlns="http://www.scons.org/dbxsd/v1.0">CacheDir</function> +is added to a build, +or after using the +<option>--cache-disable</option> +option. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +When using +<function xmlns="http://www.scons.org/dbxsd/v1.0">CacheDir</function>, +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will report, +"Retrieved `file' from cache," +unless the +<option>--cache-show</option> +option is being used. +When the +<option>--cache-show</option> +option is used, +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will print the action that +<emphasis>would</emphasis> +have been used to build the file, +without any indication that +the file was actually retrieved from the cache. +This is useful to generate build logs +that are equivalent regardless of whether +a given derived file has been built in-place +or retrieved from the cache. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-NoCache"><function>NoCache</function></link> +method can be used to disable caching of specific files. This can be +useful if inputs and/or outputs of some tool are impossible to +predict or prohibitively large. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Clean"> + <term> + <literal>Clean(targets, files_or_dirs)</literal> + </term> + <term> + <literal>env.Clean(targets, files_or_dirs)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This specifies a list of files or directories which should be removed +whenever the targets are specified with the +<option>-c</option> +command line option. +The specified targets may be a list +or an individual target. +Multiple calls to +<function xmlns="http://www.scons.org/dbxsd/v1.0">Clean</function> +are legal, +and create new targets or add files and directories to the +clean list for the specified targets. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Multiple files or directories should be specified +either as separate arguments to the +<function xmlns="http://www.scons.org/dbxsd/v1.0">Clean</function> +method, or as a list. +<function xmlns="http://www.scons.org/dbxsd/v1.0">Clean</function> +will also accept the return value of any of the construction environment +Builder methods. +Examples: +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The related +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-NoClean"><function>NoClean</function></link> +function overrides calling +<function xmlns="http://www.scons.org/dbxsd/v1.0">Clean</function> +for the same target, +and any targets passed to both functions will +<emphasis>not</emphasis> +be removed by the +<option>-c</option> +option. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +Clean('foo', ['bar', 'baz']) +Clean('dist', env.Program('hello', 'hello.c')) +Clean(['foo', 'bar'], 'something_else_to_clean') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +In this example, +installing the project creates a subdirectory for the documentation. +This statement causes the subdirectory to be removed +if the project is deinstalled. +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +Clean(docdir, os.path.join(docdir, projectname)) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Clone"> + <term> + <literal>env.Clone([key=val, ...])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Returns a separate copy of a construction environment. +If there are any keyword arguments specified, +they are added to the returned copy, +overwriting any existing values +for the keywords. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env2 = env.Clone() +env3 = env.Clone(CCFLAGS = '-g') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Additionally, a list of tools and a toolpath may be specified, as in +the Environment constructor: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +def MyTool(env): env['FOO'] = 'bar' +env4 = env.Clone(tools = ['msvc', MyTool]) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The +<varname>parse_flags</varname> +keyword argument is also recognized: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# create an environment for compiling programs that use wxWidgets +wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Command"> + <term> + <literal>Command(target, source, action, [key=val, ...])</literal> + </term> + <term> + <literal>env.Command(target, source, action, [key=val, ...])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Executes a specific action +(or list of actions) +to build a target file or files. +This is more convenient +than defining a separate Builder object +for a single special-case build. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +As a special case, the +<varname>source_scanner</varname> +keyword argument can +be used to specify +a Scanner object +that will be used to scan the sources. +(The global +<literal>DirScanner</literal> +object can be used +if any of the sources will be directories +that must be scanned on-disk for +changes to files that aren't +already specified in other Builder of function calls.) +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Any other keyword arguments specified override any +same-named existing construction variables. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +An action can be an external command, +specified as a string, +or a callable Python object; +see "Action Objects," below, +for more complete information. +Also note that a string specifying an external command +may be preceded by an +<literal>@</literal> +(at-sign) +to suppress printing the command in question, +or by a +<literal>-</literal> +(hyphen) +to ignore the exit status of the external command. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Command('foo.out', 'foo.in', + "$FOO_BUILD < $SOURCES > $TARGET") + +env.Command('bar.out', 'bar.in', + ["rm -f $TARGET", + "$BAR_BUILD < $SOURCES > $TARGET"], + ENV = {'PATH' : '/usr/local/bin/'}) + +def rename(env, target, source): + import os + os.rename('.tmp', str(target[0])) + +env.Command('baz.out', 'baz.in', + ["$BAZ_BUILD < $SOURCES > .tmp", + rename ]) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that the +<function xmlns="http://www.scons.org/dbxsd/v1.0">Command</function> +function will usually assume, by default, +that the specified targets and/or sources are Files, +if no other part of the configuration +identifies what type of entry it is. +If necessary, you can explicitly specify +that targets or source nodes should +be treated as directoriese +by using the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Dir"><function>Dir</function></link> +or +<function>env.Dir</function>() +functions. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET') + +env['DISTDIR'] = 'destination/directory' +env.Command(env.Dir('$DISTDIR')), None, make_distdir) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +(Also note that SCons will usually +automatically create any directory necessary to hold a target file, +so you normally don't need to create directories by hand.) +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Configure"> + <term> + <literal>Configure(env, [custom_tests, conf_dir, log_file, config_h])</literal> + </term> + <term> + <literal>env.Configure([custom_tests, conf_dir, log_file, config_h])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Creates a Configure object for integrated +functionality similar to GNU autoconf. +See the section "Configure Contexts," +below, for a complete explanation of the arguments and behavior. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Copy"> + <term> + <literal>env.Copy([key=val, ...])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +A now-deprecated synonym for +<function>env.Clone</function>(). +</para> +</listitem> + </varlistentry> + <varlistentry id="f-CVS"> + <term> + <literal>env.CVS(repository, module)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +A factory function that +returns a Builder object +to be used to fetch source files +from the specified +CVS +<varname>repository</varname>. +The returned Builder +is intended to be passed to the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-SourceCode"><function>SourceCode</function></link> +function. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This function is deprecated. For details, see the entry for the +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function> +function. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The optional specified +<varname>module</varname> +will be added to the beginning +of all repository path names; +this can be used, in essence, +to strip initial directory names +from the repository path names, +so that you only have to +replicate part of the repository +directory hierarchy in your +local build directory. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# Will fetch foo/bar/src.c +# from /usr/local/CVSROOT/foo/bar/src.c. +env.SourceCode('.', env.CVS('/usr/local/CVSROOT')) + +# Will fetch bar/src.c +# from /usr/local/CVSROOT/foo/bar/src.c. +env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo')) + +# Will fetch src.c +# from /usr/local/CVSROOT/foo/bar/src.c. +env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar')) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Decider"> + <term> + <literal>Decider(function)</literal> + </term> + <term> + <literal>env.Decider(function)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Specifies that all up-to-date decisions for +targets built through this construction environment +will be handled by the specified +<varname>function</varname>. +The +<varname>function</varname> +can be one of the following strings +that specify the type of decision function +to be performed: +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<variablelist> +<varlistentry> +<term><literal>timestamp-newer</literal></term> +<listitem> +<para> +Specifies that a target shall be considered out of date and rebuilt +if the dependency's timestamp is newer than the target file's timestamp. +This is the behavior of the classic Make utility, +and +<literal>make</literal> +can be used a synonym for +<literal>timestamp-newer</literal>. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>timestamp-match</literal></term> +<listitem> +<para> +Specifies that a target shall be considered out of date and rebuilt +if the dependency's timestamp is different than the +timestamp recorded the last time the target was built. +This provides behavior very similar to the classic Make utility +(in particular, files are not opened up so that their +contents can be checksummed) +except that the target will also be rebuilt if a +dependency file has been restored to a version with an +<emphasis>earlier</emphasis> +timestamp, such as can happen when restoring files from backup archives. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>MD5</literal></term> +<listitem> +<para> +Specifies that a target shall be considered out of date and rebuilt +if the dependency's content has changed sine the last time +the target was built, +as determined be performing an MD5 checksum +on the dependency's contents +and comparing it to the checksum recorded the +last time the target was built. +<literal>content</literal> +can be used as a synonym for +<literal>MD5</literal>. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>MD5-timestamp</literal></term> +<listitem> +<para> +Specifies that a target shall be considered out of date and rebuilt +if the dependency's content has changed sine the last time +the target was built, +except that dependencies with a timestamp that matches +the last time the target was rebuilt will be +assumed to be up-to-date and +<emphasis>not</emphasis> +rebuilt. +This provides behavior very similar +to the +<literal>MD5</literal> +behavior of always checksumming file contents, +with an optimization of not checking +the contents of files whose timestamps haven't changed. +The drawback is that SCons will +<emphasis>not</emphasis> +detect if a file's content has changed +but its timestamp is the same, +as might happen in an automated script +that runs a build, +updates a file, +and runs the build again, +all within a single second. +</para> +</listitem> +</varlistentry> +</variablelist> +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# Use exact timestamp matches by default. +Decider('timestamp-match') + +# Use MD5 content signatures for any targets built +# with the attached construction environment. +env.Decider('content') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +In addition to the above already-available functions, +the +<varname>function</varname> +argument may be an actual Python function +that takes the following three arguments: +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<variablelist> +<varlistentry> +<term><parameter>dependency</parameter></term> +<listitem> +<para> +The Node (file) which +should cause the +<varname>target</varname> +to be rebuilt +if it has "changed" since the last tme +<varname>target</varname> +was built. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><parameter>target</parameter></term> +<listitem> +<para> +The Node (file) being built. +In the normal case, +this is what should get rebuilt +if the +<varname>dependency</varname> +has "changed." +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><parameter>prev_ni</parameter></term> +<listitem> +<para> +Stored information about the state of the +<varname>dependency</varname> +the last time the +<varname>target</varname> +was built. +This can be consulted to match various +file characteristics +such as the timestamp, +size, or content signature. +</para> +</listitem> +</varlistentry> +</variablelist> +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The +<varname>function</varname> +should return a +<literal>True</literal> +(non-zero) +value if the +<varname>dependency</varname> +has "changed" since the last time +the +<varname>target</varname> +was built +(indicating that the target +<emphasis>should</emphasis> +be rebuilt), +and +<literal>False</literal> +(zero) +otherwise +(indicating that the target should +<emphasis>not</emphasis> +be rebuilt). +Note that the decision can be made +using whatever criteria are appopriate. +Ignoring some or all of the function arguments +is perfectly normal. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +def my_decider(dependency, target, prev_ni): + return not os.path.exists(str(target)) + +env.Decider(my_decider) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Default"> + <term> + <literal>Default(targets)</literal> + </term> + <term> + <literal>env.Default(targets)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This specifies a list of default targets, +which will be built by +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +if no explicit targets are given on the command line. +Multiple calls to +<function xmlns="http://www.scons.org/dbxsd/v1.0">Default</function> +are legal, +and add to the list of default targets. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Multiple targets should be specified as +separate arguments to the +<function xmlns="http://www.scons.org/dbxsd/v1.0">Default</function> +method, or as a list. +<function xmlns="http://www.scons.org/dbxsd/v1.0">Default</function> +will also accept the Node returned by any +of a construction environment's +builder methods. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +Default('foo', 'bar', 'baz') +env.Default(['a', 'b', 'c']) +hello = env.Program('hello', 'hello.c') +env.Default(hello) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +An argument to +<function xmlns="http://www.scons.org/dbxsd/v1.0">Default</function> +of +<literal>None</literal> +will clear all default targets. +Later calls to +<function xmlns="http://www.scons.org/dbxsd/v1.0">Default</function> +will add to the (now empty) default-target list +like normal. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The current list of targets added using the +<function xmlns="http://www.scons.org/dbxsd/v1.0">Default</function> +function or method is available in the +<literal>DEFAULT_TARGETS</literal> +list; +see below. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-DefaultEnvironment"> + <term> + <literal>DefaultEnvironment([args])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Creates and returns a default construction environment object. +This construction environment is used internally by SCons +in order to execute many of the global functions in this list, +and to fetch source files transparently +from source code management systems. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Depends"> + <term> + <literal>Depends(target, dependency)</literal> + </term> + <term> + <literal>env.Depends(target, dependency)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Specifies an explicit dependency; +the +<varname>target</varname> +will be rebuilt +whenever the +<varname>dependency</varname> +has changed. +Both the specified +<varname>target</varname> +and +<varname>dependency</varname> +can be a string +(usually the path name of a file or directory) +or Node objects, +or a list of strings or Node objects +(such as returned by a Builder call). +This should only be necessary +for cases where the dependency +is not caught by a Scanner +for the file. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Depends('foo', 'other-input-file-for-foo') + +mylib = env.Library('mylib.c') +installed_lib = env.Install('lib', mylib) +bar = env.Program('bar.c') + +# Arrange for the library to be copied into the installation +# directory before trying to build the "bar" program. +# (Note that this is for example only. A "real" library +# dependency would normally be configured through the $LIBS +# and $LIBPATH variables, not using an env.Depends() call.) + +env.Depends(bar, installed_lib) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Dictionary"> + <term> + <literal>env.Dictionary([vars])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Returns a dictionary object +containing copies of all of the +construction variables in the environment. +If there are any variable names specified, +only the specified construction +variables are returned in the dictionary. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +dict = env.Dictionary() +cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Dir"> + <term> + <literal>Dir(name, [directory])</literal> + </term> + <term> + <literal>env.Dir(name, [directory])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This returns a Directory Node, +an object that represents the specified directory +<varname>name</varname>. +<varname>name</varname> +can be a relative or absolute path. +<varname>directory</varname> +is an optional directory that will be used as the parent directory. +If no +<varname>directory</varname> +is specified, the current script's directory is used as the parent. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If +<varname>name</varname> +is a list, SCons returns a list of Dir nodes. +Construction variables are expanded in +<varname>name</varname>. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Directory Nodes can be used anywhere you +would supply a string as a directory name +to a Builder method or function. +Directory Nodes have attributes and methods +that are useful in many situations; +see "File and Directory Nodes," below. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Dump"> + <term> + <literal>env.Dump([key])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Returns a pretty printable representation of the environment. +<varname>key</varname>, +if not +<literal>None</literal>, +should be a string containing the name of the variable of interest. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This SConstruct: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env=Environment() +print env.Dump('CCCOM') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +will print: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES' +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +While this SConstruct: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env=Environment() +print env.Dump() +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +will print: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +{ 'AR': 'ar', + 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET', + 'ARFLAGS': ['r'], + 'AS': 'as', + 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES', + 'ASFLAGS': [], + ... +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-EnsurePythonVersion"> + <term> + <literal>EnsurePythonVersion(major, minor)</literal> + </term> + <term> + <literal>env.EnsurePythonVersion(major, minor)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Ensure that the Python version is at least +<varname>major</varname>.<varname>minor</varname>. +This function will +print out an error message and exit SCons with a non-zero exit code if the +actual Python version is not late enough. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +EnsurePythonVersion(2,2) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-EnsureSConsVersion"> + <term> + <literal>EnsureSConsVersion(major, minor, [revision])</literal> + </term> + <term> + <literal>env.EnsureSConsVersion(major, minor, [revision])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Ensure that the SCons version is at least +<varname>major.minor</varname>, +or +<varname>major.minor.revision</varname>. +if +<varname>revision</varname> +is specified. +This function will +print out an error message and exit SCons with a non-zero exit code if the +actual SCons version is not late enough. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +EnsureSConsVersion(0,14) + +EnsureSConsVersion(0,96,90) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Environment"> + <term> + <literal>Environment([key=value, ...])</literal> + </term> + <term> + <literal>env.Environment([key=value, ...])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Return a new construction environment +initialized with the specified +<varname>key</varname><literal>=</literal><varname>value</varname> +pairs. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Execute"> + <term> + <literal>Execute(action, [strfunction, varlist])</literal> + </term> + <term> + <literal>env.Execute(action, [strfunction, varlist])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Executes an Action object. +The specified +<varname>action</varname> +may be an Action object +(see the section "Action Objects," +below, for a complete explanation of the arguments and behavior), +or it may be a command-line string, +list of commands, +or executable Python function, +each of which will be converted +into an Action object +and then executed. +The exit value of the command +or return value of the Python function +will be returned. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will print an error message if the executed +<varname>action</varname> +fails--that is, +exits with or returns a non-zero value. +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will +<emphasis>not</emphasis>, +however, +automatically terminate the build +if the specified +<varname>action</varname> +fails. +If you want the build to stop in response to a failed +<function xmlns="http://www.scons.org/dbxsd/v1.0">Execute</function> +call, +you must explicitly check for a non-zero return value: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +Execute(Copy('file.out', 'file.in')) + +if Execute("mkdir sub/dir/ectory"): + # The mkdir failed, don't try to build. + Exit(1) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Exit"> + <term> + <literal>Exit([value])</literal> + </term> + <term> + <literal>env.Exit([value])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This tells +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +to exit immediately +with the specified +<varname>value</varname>. +A default exit value of +<literal>0</literal> +(zero) +is used if no value is specified. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Export"> + <term> + <literal>Export(vars)</literal> + </term> + <term> + <literal>env.Export(vars)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This tells +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +to export a list of variables from the current +SConscript file to all other SConscript files. +The exported variables are kept in a global collection, +so subsequent calls to +<function xmlns="http://www.scons.org/dbxsd/v1.0">Export</function> +will over-write previous exports that have the same name. +Multiple variable names can be passed to +<function xmlns="http://www.scons.org/dbxsd/v1.0">Export</function> +as separate arguments or as a list. +Keyword arguments can be used to provide names and their values. +A dictionary can be used to map variables to a different name when exported. +Both local variables and global variables can be exported. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env = Environment() +# Make env available for all SConscript files to Import(). +Export("env") + +package = 'my_name' +# Make env and package available for all SConscript files:. +Export("env", "package") + +# Make env and package available for all SConscript files: +Export(["env", "package"]) + +# Make env available using the name debug: +Export(debug = env) + +# Make env available using the name debug: +Export({"debug":env}) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that the +<function xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</function> +function supports an +<varname>exports</varname> +argument that makes it easier to to export a variable or +set of variables to a single SConscript file. +See the description of the +<function xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</function> +function, below. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-File"> + <term> + <literal>File(name, [directory])</literal> + </term> + <term> + <literal>env.File(name, [directory])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This returns a +File Node, +an object that represents the specified file +<varname>name</varname>. +<varname>name</varname> +can be a relative or absolute path. +<varname>directory</varname> +is an optional directory that will be used as the parent directory. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If +<varname>name</varname> +is a list, SCons returns a list of File nodes. +Construction variables are expanded in +<varname>name</varname>. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +File Nodes can be used anywhere you +would supply a string as a file name +to a Builder method or function. +File Nodes have attributes and methods +that are useful in many situations; +see "File and Directory Nodes," below. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-FindFile"> + <term> + <literal>FindFile(file, dirs)</literal> + </term> + <term> + <literal>env.FindFile(file, dirs)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Search for +<varname>file</varname> +in the path specified by +<varname>dirs</varname>. +<varname>dirs</varname> +may be a list of directory names or a single directory name. +In addition to searching for files that exist in the filesystem, +this function also searches for derived files +that have not yet been built. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +foo = env.FindFile('foo', ['dir1', 'dir2']) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-FindInstalledFiles"> + <term> + <literal>FindInstalledFiles()</literal> + </term> + <term> + <literal>env.FindInstalledFiles()</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Returns the list of targets set up by the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-Install"><function>Install</function></link> +or +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-InstallAs"><function>InstallAs</function></link> +builders. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This function serves as a convenient method to select the contents of +a binary package. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +Install( '/bin', [ 'executable_a', 'executable_b' ] ) + +# will return the file node list +# [ '/bin/executable_a', '/bin/executable_b' ] +FindInstalledFiles() + +Install( '/lib', [ 'some_library' ] ) + +# will return the file node list +# [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ] +FindInstalledFiles() +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-FindPathDirs"> + <term> + <literal>FindPathDirs(variable)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Returns a function +(actually a callable Python object) +intended to be used as the +<varname>path_function</varname> +of a Scanner object. +The returned object will look up the specified +<varname>variable</varname> +in a construction environment +and treat the construction variable's value as a list of +directory paths that should be searched +(like +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-CPPPATH"><envar>$CPPPATH</envar></link>, +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LIBPATH"><envar>$LIBPATH</envar></link>, +etc.). +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that use of +<function xmlns="http://www.scons.org/dbxsd/v1.0">FindPathDirs</function> +is generally preferable to +writing your own +<varname>path_function</varname> +for the following reasons: +1) The returned list will contain all appropriate directories +found in source trees +(when +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-VariantDir"><function>VariantDir</function></link> +is used) +or in code repositories +(when +<function xmlns="http://www.scons.org/dbxsd/v1.0">Repository</function> +or the +<option>-Y</option> +option are used). +2) scons will identify expansions of +<varname>variable</varname> +that evaluate to the same list of directories as, +in fact, the same list, +and avoid re-scanning the directories for files, +when possible. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +def my_scan(node, env, path, arg): + # Code to scan file contents goes here... + return include_files + +scanner = Scanner(name = 'myscanner', + function = my_scan, + path_function = FindPathDirs('MYPATH')) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-FindSourceFiles"> + <term> + <literal>FindSourceFiles(node='"."')</literal> + </term> + <term> + <literal>env.FindSourceFiles(node='"."')</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Returns the list of nodes which serve as the source of the built files. +It does so by inspecting the dependency tree starting at the optional +argument +<varname>node</varname> +which defaults to the '"."'-node. It will then return all leaves of +<varname>node</varname>. +These are all children which have no further children. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This function is a convenient method to select the contents of a Source +Package. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +Program( 'src/main_a.c' ) +Program( 'src/main_b.c' ) +Program( 'main_c.c' ) + +# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c'] +FindSourceFiles() + +# returns ['src/main_b.c', 'src/main_a.c' ] +FindSourceFiles( 'src' ) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +As you can see build support files (SConstruct in the above example) +will also be returned by this function. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Flatten"> + <term> + <literal>Flatten(sequence)</literal> + </term> + <term> + <literal>env.Flatten(sequence)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Takes a sequence (that is, a Python list or tuple) +that may contain nested sequences +and returns a flattened list containing +all of the individual elements in any sequence. +This can be helpful for collecting +the lists returned by calls to Builders; +other Builders will automatically +flatten lists specified as input, +but direct Python manipulation of +these lists does not. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +foo = Object('foo.c') +bar = Object('bar.c') + +# Because `foo' and `bar' are lists returned by the Object() Builder, +# `objects' will be a list containing nested lists: +objects = ['f1.o', foo, 'f2.o', bar, 'f3.o'] + +# Passing such a list to another Builder is all right because +# the Builder will flatten the list automatically: +Program(source = objects) + +# If you need to manipulate the list directly using Python, you need to +# call Flatten() yourself, or otherwise handle nested lists: +for object in Flatten(objects): + print str(object) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-GetBuildFailures"> + <term> + <literal>GetBuildFailures()</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Returns a list of exceptions for the +actions that failed while +attempting to build targets. +Each element in the returned list is a +<classname>BuildError</classname> +object +with the following attributes +that record various aspects +of the build failure: +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>.node</literal> +The node that was being built +when the build failure occurred. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>.status</literal> +The numeric exit status +returned by the command or Python function +that failed when trying to build the +specified Node. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>.errstr</literal> +The SCons error string +describing the build failure. +(This is often a generic +message like "Error 2" +to indicate that an executed +command exited with a status of 2.) +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>.filename</literal> +The name of the file or +directory that actually caused the failure. +This may be different from the +<literal>.node</literal> +attribute. +For example, +if an attempt to build a target named +<filename>sub/dir/target</filename> +fails because the +<filename>sub/dir</filename> +directory could not be created, +then the +<literal>.node</literal> +attribute will be +<filename>sub/dir/target</filename> +but the +<literal>.filename</literal> +attribute will be +<filename>sub/dir</filename>. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>.executor</literal> +The SCons Executor object +for the target Node +being built. +This can be used to retrieve +the construction environment used +for the failed action. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>.action</literal> +The actual SCons Action object that failed. +This will be one specific action +out of the possible list of +actions that would have been +executed to build the target. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>.command</literal> +The actual expanded command that was executed and failed, +after expansion of +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-TARGET"><envar>$TARGET</envar></link>, +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SOURCE"><envar>$SOURCE</envar></link>, +and other construction variables. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that the +<function xmlns="http://www.scons.org/dbxsd/v1.0">GetBuildFailures</function> +function +will always return an empty list +until any build failure has occurred, +which means that +<function xmlns="http://www.scons.org/dbxsd/v1.0">GetBuildFailures</function> +will always return an empty list +while the +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename> +files are being read. +Its primary intended use is +for functions that will be +executed before SCons exits +by passing them to the +standard Python +<function>atexit.register</function>() +function. +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +import atexit + +def print_build_failures(): + from SCons.Script import GetBuildFailures + for bf in GetBuildFailures(): + print "%s failed: %s" % (bf.node, bf.errstr) + +atexit.register(print_build_failures) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-GetBuildPath"> + <term> + <literal>GetBuildPath(file, [...])</literal> + </term> + <term> + <literal>env.GetBuildPath(file, [...])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Returns the +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +path name (or names) for the specified +<varname>file</varname> +(or files). +The specified +<varname>file</varname> +or files +may be +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +Nodes or strings representing path names. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-GetLaunchDir"> + <term> + <literal>GetLaunchDir()</literal> + </term> + <term> + <literal>env.GetLaunchDir()</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Returns the absolute path name of the directory from which +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +was initially invoked. +This can be useful when using the +<option>-u</option>, +<option>-U</option> +or +<option>-D</option> +options, which internally +change to the directory in which the +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConstruct</filename> +file is found. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-GetOption"> + <term> + <literal>GetOption(name)</literal> + </term> + <term> + <literal>env.GetOption(name)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This function provides a way to query the value of +SCons options set on scons command line +(or set using the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-SetOption"><function>SetOption</function></link> +function). +The options supported are: +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<variablelist> +<varlistentry> +<term><literal>cache_debug</literal></term> +<listitem> +<para> +which corresponds to --cache-debug; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>cache_disable</literal></term> +<listitem> +<para> +which corresponds to --cache-disable; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>cache_force</literal></term> +<listitem> +<para> +which corresponds to --cache-force; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>cache_show</literal></term> +<listitem> +<para> +which corresponds to --cache-show; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>clean</literal></term> +<listitem> +<para> +which corresponds to -c, --clean and --remove; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>config</literal></term> +<listitem> +<para> +which corresponds to --config; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>directory</literal></term> +<listitem> +<para> +which corresponds to -C and --directory; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>diskcheck</literal></term> +<listitem> +<para> +which corresponds to --diskcheck +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>duplicate</literal></term> +<listitem> +<para> +which corresponds to --duplicate; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>file</literal></term> +<listitem> +<para> +which corresponds to -f, --file, --makefile and --sconstruct; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>help</literal></term> +<listitem> +<para> +which corresponds to -h and --help; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>ignore_errors</literal></term> +<listitem> +<para> +which corresponds to --ignore-errors; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>implicit_cache</literal></term> +<listitem> +<para> +which corresponds to --implicit-cache; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>implicit_deps_changed</literal></term> +<listitem> +<para> +which corresponds to --implicit-deps-changed; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>implicit_deps_unchanged</literal></term> +<listitem> +<para> +which corresponds to --implicit-deps-unchanged; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>interactive</literal></term> +<listitem> +<para> +which corresponds to --interact and --interactive; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>keep_going</literal></term> +<listitem> +<para> +which corresponds to -k and --keep-going; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>max_drift</literal></term> +<listitem> +<para> +which corresponds to --max-drift; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>no_exec</literal></term> +<listitem> +<para> +which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>no_site_dir</literal></term> +<listitem> +<para> +which corresponds to --no-site-dir; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>num_jobs</literal></term> +<listitem> +<para> +which corresponds to -j and --jobs; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>profile_file</literal></term> +<listitem> +<para> +which corresponds to --profile; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>question</literal></term> +<listitem> +<para> +which corresponds to -q and --question; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>random</literal></term> +<listitem> +<para> +which corresponds to --random; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>repository</literal></term> +<listitem> +<para> +which corresponds to -Y, --repository and --srcdir; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>silent</literal></term> +<listitem> +<para> +which corresponds to -s, --silent and --quiet; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>site_dir</literal></term> +<listitem> +<para> +which corresponds to --site-dir; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>stack_size</literal></term> +<listitem> +<para> +which corresponds to --stack-size; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>taskmastertrace_file</literal></term> +<listitem> +<para> +which corresponds to --taskmastertrace; and +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>warn</literal></term> +<listitem> +<para> +which corresponds to --warn and --warning. +</para> +</listitem> +</varlistentry> +</variablelist> +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +See the documentation for the +corresponding command line object for information about each specific +option. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Glob"> + <term> + <literal>Glob(pattern, [ondisk, source, strings])</literal> + </term> + <term> + <literal>env.Glob(pattern, [ondisk, source, strings])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Returns Nodes (or strings) that match the specified +<varname>pattern</varname>, +relative to the directory of the current +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename> +file. +The +<function>env.Glob</function>() +form performs string substition on +<varname>pattern</varname> +and returns whatever matches +the resulting expanded pattern. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The specified +<varname>pattern</varname> +uses Unix shell style metacharacters for matching: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + * matches everything + ? matches any single character + [seq] matches any character in seq + [!seq] matches any char not in seq +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the first character of a filename is a dot, +it must be matched explicitly. +Character matches do +<emphasis>not</emphasis> +span directory separators. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The +<function xmlns="http://www.scons.org/dbxsd/v1.0">Glob</function> +knows about +repositories +(see the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Repository"><function>Repository</function></link> +function) +and source directories +(see the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-VariantDir"><function>VariantDir</function></link> +function) +and +returns a Node (or string, if so configured) +in the local (SConscript) directory +if matching Node is found +anywhere in a corresponding +repository or source directory. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The +<varname>ondisk</varname> +argument may be set to +<literal>False</literal> +(or any other non-true value) +to disable the search for matches on disk, +thereby only returning matches among +already-configured File or Dir Nodes. +The default behavior is to +return corresponding Nodes +for any on-disk matches found. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The +<varname>source</varname> +argument may be set to +<literal>True</literal> +(or any equivalent value) +to specify that, +when the local directory is a +<function xmlns="http://www.scons.org/dbxsd/v1.0">VariantDir</function>, +the returned Nodes should be from the +corresponding source directory, +not the local directory. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The +<varname>strings</varname> +argument may be set to +<literal>True</literal> +(or any equivalent value) +to have the +<function xmlns="http://www.scons.org/dbxsd/v1.0">Glob</function> +function return strings, not Nodes, +that represent the matched files or directories. +The returned strings will be relative to +the local (SConscript) directory. +(Note that This may make it easier to perform +arbitrary manipulation of file names, +but if the returned strings are +passed to a different +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename> +file, +any Node translation will be relative +to the other +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename> +directory, +not the original +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename> +directory.) +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +Program('foo', Glob('*.c')) +Zip('/tmp/everything', Glob('.??*') + Glob('*')) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Help"> + <term> + <literal>Help(text)</literal> + </term> + <term> + <literal>env.Help(text)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This specifies help text to be printed if the +<option>-h</option> +argument is given to +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>. +If +<function xmlns="http://www.scons.org/dbxsd/v1.0">Help</function> +is called multiple times, the text is appended together in the order +that +<function xmlns="http://www.scons.org/dbxsd/v1.0">Help</function> +is called. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Ignore"> + <term> + <literal>Ignore(target, dependency)</literal> + </term> + <term> + <literal>env.Ignore(target, dependency)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The specified dependency file(s) +will be ignored when deciding if +the target file(s) need to be rebuilt. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +You can also use +<function xmlns="http://www.scons.org/dbxsd/v1.0">Ignore</function> +to remove a target from the default build. +In order to do this you must specify the directory the target will +be built in as the target, and the file you want to skip building +as the dependency. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that this will only remove the dependencies listed from +the files built by default. It will still be built if that +dependency is needed by another object being built. +See the third and forth examples below. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Ignore('foo', 'foo.c') +env.Ignore('bar', ['bar1.h', 'bar2.h']) +env.Ignore('.','foobar.obj') +env.Ignore('bar','bar/foobar.obj') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Import"> + <term> + <literal>Import(vars)</literal> + </term> + <term> + <literal>env.Import(vars)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This tells +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +to import a list of variables into the current SConscript file. This +will import variables that were exported with +<function xmlns="http://www.scons.org/dbxsd/v1.0">Export</function> +or in the +<varname>exports</varname> +argument to +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-SConscript"><function>SConscript</function></link>. +Variables exported by +<function xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</function> +have precedence. +Multiple variable names can be passed to +<function xmlns="http://www.scons.org/dbxsd/v1.0">Import</function> +as separate arguments or as a list. The variable "*" can be used +to import all variables. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +Import("env") +Import("env", "variable") +Import(["env", "variable"]) +Import("*") +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Literal"> + <term> + <literal>Literal(string)</literal> + </term> + <term> + <literal>env.Literal(string)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The specified +<varname>string</varname> +will be preserved as-is +and not have construction variables expanded. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Local"> + <term> + <literal>Local(targets)</literal> + </term> + <term> + <literal>env.Local(targets)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The specified +<varname>targets</varname> +will have copies made in the local tree, +even if an already up-to-date copy +exists in a repository. +Returns a list of the target Node or Nodes. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-MergeFlags"> + <term> + <literal>env.MergeFlags(arg, [unique])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Merges the specified +<varname>arg</varname> +values to the construction environment's construction variables. +If the +<varname>arg</varname> +argument is not a dictionary, +it is converted to one by calling +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-ParseFlags"><function>env.ParseFlags</function></link> +on the argument +before the values are merged. +Note that +<varname>arg</varname> +must be a single value, +so multiple strings must +be passed in as a list, +not as separate arguments to +<function xmlns="http://www.scons.org/dbxsd/v1.0">env.MergeFlags</function>. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +By default, +duplicate values are eliminated; +you can, however, specify +<literal>unique=0</literal> +to allow duplicate +values to be added. +When eliminating duplicate values, +any construction variables that end with +the string +<literal>PATH</literal> +keep the left-most unique value. +All other construction variables keep +the right-most unique value. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# Add an optimization flag to $CCFLAGS. +env.MergeFlags('-O3') + +# Combine the flags returned from running pkg-config with an optimization +# flag and merge the result into the construction variables. +env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3']) + +# Combine an optimization flag with the flags returned from running pkg-config +# twice and merge the result into the construction variables. +env.MergeFlags(['-O3', + '!pkg-config gtk+-2.0 --cflags --libs', + '!pkg-config libpng12 --cflags --libs']) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-NoCache"> + <term> + <literal>NoCache(target, ...)</literal> + </term> + <term> + <literal>env.NoCache(target, ...)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Specifies a list of files which should +<emphasis>not</emphasis> +be cached whenever the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-CacheDir"><function>CacheDir</function></link> +method has been activated. +The specified targets may be a list +or an individual target. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Multiple files should be specified +either as separate arguments to the +<function xmlns="http://www.scons.org/dbxsd/v1.0">NoCache</function> +method, or as a list. +<function xmlns="http://www.scons.org/dbxsd/v1.0">NoCache</function> +will also accept the return value of any of the construction environment +Builder methods. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Calling +<function xmlns="http://www.scons.org/dbxsd/v1.0">NoCache</function> +on directories and other non-File Node types has no effect because +only File Nodes are cached. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +NoCache('foo.elf') +NoCache(env.Program('hello', 'hello.c')) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-NoClean"> + <term> + <literal>NoClean(target, ...)</literal> + </term> + <term> + <literal>env.NoClean(target, ...)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Specifies a list of files or directories which should +<emphasis>not</emphasis> +be removed whenever the targets (or their dependencies) +are specified with the +<option>-c</option> +command line option. +The specified targets may be a list +or an individual target. +Multiple calls to +<function xmlns="http://www.scons.org/dbxsd/v1.0">NoClean</function> +are legal, +and prevent each specified target +from being removed by calls to the +<option>-c</option> +option. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Multiple files or directories should be specified +either as separate arguments to the +<function xmlns="http://www.scons.org/dbxsd/v1.0">NoClean</function> +method, or as a list. +<function xmlns="http://www.scons.org/dbxsd/v1.0">NoClean</function> +will also accept the return value of any of the construction environment +Builder methods. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Calling +<function xmlns="http://www.scons.org/dbxsd/v1.0">NoClean</function> +for a target overrides calling +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Clean"><function>Clean</function></link> +for the same target, +and any targets passed to both functions will +<emphasis>not</emphasis> +be removed by the +<option>-c</option> +option. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +NoClean('foo.elf') +NoClean(env.Program('hello', 'hello.c')) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-ParseConfig"> + <term> + <literal>env.ParseConfig(command, [function, unique])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Calls the specified +<varname>function</varname> +to modify the environment as specified by the output of +<varname>command</varname>. +The default +<varname>function</varname> +is +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-MergeFlags"><function>env.MergeFlags</function></link>, +which expects the output of a typical +<application>*-config</application> +command +(for example, +<application>gtk-config</application>) +and adds the options +to the appropriate construction variables. +By default, +duplicate values are not +added to any construction variables; +you can specify +<literal>unique=0</literal> +to allow duplicate +values to be added. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Interpreted options +and the construction variables they affect +are as specified for the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-ParseFlags"><function>env.ParseFlags</function></link> +method (which this method calls). +See that method's description, below, +for a table of options and construction variables. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-ParseDepends"> + <term> + <literal>ParseDepends(filename, [must_exist, only_one])</literal> + </term> + <term> + <literal>env.ParseDepends(filename, [must_exist, only_one])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Parses the contents of the specified +<varname>filename</varname> +as a list of dependencies in the style of +<application xmlns="http://www.scons.org/dbxsd/v1.0">Make</application> +or +<application>mkdep</application>, +and explicitly establishes all of the listed dependencies. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +By default, +it is not an error +if the specified +<varname>filename</varname> +does not exist. +The optional +<varname>must_exist</varname> +argument may be set to a non-zero +value to have +scons +throw an exception and +generate an error if the file does not exist, +or is otherwise inaccessible. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The optional +<varname>only_one</varname> +argument may be set to a non-zero +value to have +scons +thrown an exception and +generate an error +if the file contains dependency +information for more than one target. +This can provide a small sanity check +for files intended to be generated +by, for example, the +<literal>gcc -M</literal> +flag, +which should typically only +write dependency information for +one output file into a corresponding +<filename>.d</filename> +file. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The +<varname>filename</varname> +and all of the files listed therein +will be interpreted relative to +the directory of the +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename> +file which calls the +<function xmlns="http://www.scons.org/dbxsd/v1.0">ParseDepends</function> +function. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-ParseFlags"> + <term> + <literal>env.ParseFlags(flags, ...)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Parses one or more strings containing +typical command-line flags for GCC tool chains +and returns a dictionary with the flag values +separated into the appropriate SCons construction variables. +This is intended as a companion to the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-MergeFlags"><function>env.MergeFlags</function></link> +method, but allows for the values in the returned dictionary +to be modified, if necessary, +before merging them into the construction environment. +(Note that +<function xmlns="http://www.scons.org/dbxsd/v1.0">env.MergeFlags</function> +will call this method if its argument is not a dictionary, +so it is usually not necessary to call +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-ParseFlags"><function>env.ParseFlags</function></link> +directly unless you want to manipulate the values.) +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the first character in any string is +an exclamation mark (!), +the rest of the string is executed as a command, +and the output from the command is +parsed as GCC tool chain command-line flags +and added to the resulting dictionary. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Flag values are translated accordig to the prefix found, +and added to the following construction variables: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +-arch CCFLAGS, LINKFLAGS +-D CPPDEFINES +-framework FRAMEWORKS +-frameworkdir= FRAMEWORKPATH +-include CCFLAGS +-isysroot CCFLAGS, LINKFLAGS +-I CPPPATH +-l LIBS +-L LIBPATH +-mno-cygwin CCFLAGS, LINKFLAGS +-mwindows LINKFLAGS +-pthread CCFLAGS, LINKFLAGS +-std= CFLAGS +-Wa, ASFLAGS, CCFLAGS +-Wl,-rpath= RPATH +-Wl,-R, RPATH +-Wl,-R RPATH +-Wl, LINKFLAGS +-Wp, CPPFLAGS +- CCFLAGS ++ CCFLAGS, LINKFLAGS +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Any other strings not associated with options +are assumed to be the names of libraries +and added to the +<envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBS</envar> +construction variable. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples (all of which produce the same result): +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +dict = env.ParseFlags('-O2 -Dfoo -Dbar=1') +dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1') +dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1']) +dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Perforce"> + <term> + <literal>env.Perforce()</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +A factory function that +returns a Builder object +to be used to fetch source files +from the Perforce source code management system. +The returned Builder +is intended to be passed to the +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function> +function. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This function is deprecated. For details, see the entry for the +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function> +function. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.SourceCode('.', env.Perforce()) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Perforce uses a number of external +environment variables for its operation. +Consequently, this function adds the +following variables from the user's external environment +to the construction environment's +ENV dictionary: +P4CHARSET, +P4CLIENT, +P4LANGUAGE, +P4PASSWD, +P4PORT, +P4USER, +SystemRoot, +USER, +and +USERNAME. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Platform"> + <term> + <literal>Platform(string)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The +<function xmlns="http://www.scons.org/dbxsd/v1.0">Platform</function> +form returns a callable object +that can be used to initialize +a construction environment using the +platform keyword of the +<function xmlns="http://www.scons.org/dbxsd/v1.0">Environment</function> +function. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env = Environment(platform = Platform('win32')) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The +<function xmlns="http://www.scons.org/dbxsd/v1.0">env.Platform</function> +form applies the callable object for the specified platform +<varname>string</varname> +to the environment through which the method was called. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Platform('posix') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that the +<literal>win32</literal> +platform adds the +<literal>SystemDrive</literal> +and +<literal>SystemRoot</literal> +variables from the user's external environment +to the construction environment's +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-ENV"><envar>$ENV</envar></link> +dictionary. +This is so that any executed commands +that use sockets to connect with other systems +(such as fetching source files from +external CVS repository specifications like +<literal>:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons</literal>) +will work on Windows systems. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Precious"> + <term> + <literal>Precious(target, ...)</literal> + </term> + <term> + <literal>env.Precious(target, ...)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Marks each given +<varname>target</varname> +as precious so it is not deleted before it is rebuilt. Normally +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +deletes a target before building it. +Multiple targets can be passed in to a single call to +<function xmlns="http://www.scons.org/dbxsd/v1.0">Precious</function>. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Prepend"> + <term> + <literal>env.Prepend(key=val, [...])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Appends the specified keyword arguments +to the beginning of construction variables in the environment. +If the Environment does not have +the specified construction variable, +it is simply added to the environment. +If the values of the construction variable +and the keyword argument are the same type, +then the two values will be simply added together. +Otherwise, the construction variable +and the value of the keyword argument +are both coerced to lists, +and the lists are added together. +(See also the Append method, above.) +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy']) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-PrependENVPath"> + <term> + <literal>env.PrependENVPath(name, newpath, [envname, sep, delete_existing])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This appends new path elements to the given path in the +specified external environment +(<envar xmlns="http://www.scons.org/dbxsd/v1.0">$ENV</envar> +by default). +This will only add +any particular path once (leaving the first one it encounters and +ignoring the rest, to preserve path order), +and to help assure this, +will normalize all paths (using +<literal>os.path.normpath</literal> +and +<literal>os.path.normcase</literal>). +This can also handle the +case where the given old path variable is a list instead of a +string, in which case a list will be returned instead of a string. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If +<varname>delete_existing</varname> +is 0, then adding a path that already exists +will not move it to the beginning; +it will stay where it is in the list. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +print 'before:',env['ENV']['INCLUDE'] +include_path = '/foo/bar:/foo' +env.PrependENVPath('INCLUDE', include_path) +print 'after:',env['ENV']['INCLUDE'] +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The above example will print: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +before: /biz:/foo +after: /foo/bar:/foo:/biz +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-PrependUnique"> + <term> + <literal>env.PrependUnique(key=val, delete_existing=0, [...])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Appends the specified keyword arguments +to the beginning of construction variables in the environment. +If the Environment does not have +the specified construction variable, +it is simply added to the environment. +If the construction variable being appended to is a list, +then any value(s) that already exist in the +construction variable will +<emphasis>not</emphasis> +be added again to the list. +However, if delete_existing is 1, +existing matching values are removed first, so +existing values in the arg list move to the front of the list. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Progress"> + <term> + <literal>Progress(callable, [interval])</literal> + </term> + <term> + <literal>Progress(string, [interval, file, overwrite])</literal> + </term> + <term> + <literal>Progress(list_of_strings, [interval, file, overwrite])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Allows SCons to show progress made during the build +by displaying a string or calling a function while +evaluating Nodes (e.g. files). +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the first specified argument is a Python callable +(a function or an object that has a +<function>__call__</function>() +method), +the function will be called +once every +<varname>interval</varname> +times a Node is evaluated. +The callable will be passed the evaluated Node +as its only argument. +(For future compatibility, +it's a good idea to also add +<literal>*args</literal> +and +<literal>**kw</literal> +as arguments to your function or method. +This will prevent the code from breaking +if SCons ever changes the interface +to call the function with additional arguments in the future.) +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +An example of a simple custom progress function +that prints a string containing the Node name +every 10 Nodes: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +def my_progress_function(node, *args, **kw): + print 'Evaluating node %s!' % node +Progress(my_progress_function, interval=10) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +A more complicated example of a custom progress display object +that prints a string containing a count +every 100 evaluated Nodes. +Note the use of +<literal>\r</literal> +(a carriage return) +at the end so that the string +will overwrite itself on a display: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +import sys +class ProgressCounter(object): + count = 0 + def __call__(self, node, *args, **kw): + self.count += 100 + sys.stderr.write('Evaluated %s nodes\r' % self.count) +Progress(ProgressCounter(), interval=100) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the first argument +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Progress"><function>Progress</function></link> +is a string, +the string will be displayed +every +<varname>interval</varname> +evaluated Nodes. +The default is to print the string on standard output; +an alternate output stream +may be specified with the +<literal>file=</literal> +argument. +The following will print a series of dots +on the error output, +one dot for every 100 evaluated Nodes: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +import sys +Progress('.', interval=100, file=sys.stderr) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the string contains the verbatim substring +<envar xmlns="http://www.scons.org/dbxsd/v1.0">$TARGET</envar>, +it will be replaced with the Node. +Note that, for performance reasons, this is +<emphasis>not</emphasis> +a regular SCons variable substition, +so you can not use other variables +or use curly braces. +The following example will print the name of +every evaluated Node, +using a +<literal>\r</literal> +(carriage return) to cause each line to overwritten by the next line, +and the +<literal>overwrite=</literal> +keyword argument to make sure the previously-printed +file name is overwritten with blank spaces: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +import sys +Progress('$TARGET\r', overwrite=True) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the first argument to +<function xmlns="http://www.scons.org/dbxsd/v1.0">Progress</function> +is a list of strings, +then each string in the list will be displayed +in rotating fashion every +<varname>interval</varname> +evaluated Nodes. +This can be used to implement a "spinner" +on the user's screen as follows: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Pseudo"> + <term> + <literal>Pseudo(target, ...)</literal> + </term> + <term> + <literal>env.Pseudo(target, ...)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This indicates that each given +<varname>target</varname> +should not be created by the build rule, and if the target is created, +an error will be generated. This is similar to the gnu make .PHONY +target. However, in the vast majority of cases, an +<function xmlns="http://www.scons.org/dbxsd/v1.0">Alias</function> +is more appropriate. + +Multiple targets can be passed in to a single call to +<function xmlns="http://www.scons.org/dbxsd/v1.0">Pseudo</function>. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-RCS"> + <term> + <literal>env.RCS()</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +A factory function that +returns a Builder object +to be used to fetch source files +from RCS. +The returned Builder +is intended to be passed to the +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function> +function: +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This function is deprecated. For details, see the entry for the +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function> +function. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.SourceCode('.', env.RCS()) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will fetch source files +from RCS subdirectories automatically, +so configuring RCS +as demonstrated in the above example +should only be necessary if +you are fetching from +RCS,v +files in the same +directory as the source files, +or if you need to explicitly specify RCS +for a specific subdirectory. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Replace"> + <term> + <literal>env.Replace(key=val, [...])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Replaces construction variables in the Environment +with the specified keyword arguments. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Repository"> + <term> + <literal>Repository(directory)</literal> + </term> + <term> + <literal>env.Repository(directory)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Specifies that +<varname>directory</varname> +is a repository to be searched for files. +Multiple calls to +<function xmlns="http://www.scons.org/dbxsd/v1.0">Repository</function> +are legal, +and each one adds to the list of +repositories that will be searched. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +To +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>, +a repository is a copy of the source tree, +from the top-level directory on down, +which may contain +both source files and derived files +that can be used to build targets in +the local source tree. +The canonical example would be an +official source tree maintained by an integrator. +If the repository contains derived files, +then the derived files should have been built using +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>, +so that the repository contains the necessary +signature information to allow +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +to figure out when it is appropriate to +use the repository copy of a derived file, +instead of building one locally. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that if an up-to-date derived file +already exists in a repository, +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will +<emphasis>not</emphasis> +make a copy in the local directory tree. +In order to guarantee that a local copy +will be made, +use the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Local"><function>Local</function></link> +method. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Requires"> + <term> + <literal>Requires(target, prerequisite)</literal> + </term> + <term> + <literal>env.Requires(target, prerequisite)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Specifies an order-only relationship +between the specified target file(s) +and the specified prerequisite file(s). +The prerequisite file(s) +will be (re)built, if necessary, +<emphasis>before</emphasis> +the target file(s), +but the target file(s) do not actually +depend on the prerequisites +and will not be rebuilt simply because +the prerequisite file(s) change. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Requires('foo', 'file-that-must-be-built-before-foo') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Return"> + <term> + <literal>Return([vars..., stop=])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +By default, +this stops processing the current SConscript +file and returns to the calling SConscript file +the values of the variables named in the +<varname>vars</varname> +string arguments. +Multiple strings contaning variable names may be passed to +<function xmlns="http://www.scons.org/dbxsd/v1.0">Return</function>. +Any strings that contain white space +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The optional +<literal>stop=</literal> +keyword argument may be set to a false value +to continue processing the rest of the SConscript +file after the +<function xmlns="http://www.scons.org/dbxsd/v1.0">Return</function> +call. +This was the default behavior prior to SCons 0.98. +However, the values returned +are still the values of the variables in the named +<varname>vars</varname> +at the point +<function xmlns="http://www.scons.org/dbxsd/v1.0">Return</function> +is called. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# Returns without returning a value. +Return() + +# Returns the value of the 'foo' Python variable. +Return("foo") + +# Returns the values of the Python variables 'foo' and 'bar'. +Return("foo", "bar") + +# Returns the values of Python variables 'val1' and 'val2'. +Return('val1 val2') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Scanner"> + <term> + <literal>Scanner(function, [argument, keys, path_function, node_class, node_factory, scan_check, recursive])</literal> + </term> + <term> + <literal>env.Scanner(function, [argument, keys, path_function, node_class, node_factory, scan_check, recursive])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Creates a Scanner object for +the specified +<varname>function</varname>. +See the section "Scanner Objects," +below, for a complete explanation of the arguments and behavior. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-SCCS"> + <term> + <literal>env.SCCS()</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +A factory function that +returns a Builder object +to be used to fetch source files +from SCCS. +The returned Builder +is intended to be passed to the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-SourceCode"><function>SourceCode</function></link> +function. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.SourceCode('.', env.SCCS()) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will fetch source files +from SCCS subdirectories automatically, +so configuring SCCS +as demonstrated in the above example +should only be necessary if +you are fetching from +<filename>s.SCCS</filename> +files in the same +directory as the source files, +or if you need to explicitly specify SCCS +for a specific subdirectory. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-SConscript"> + <term> + <literal>SConscript(scripts, [exports, variant_dir, duplicate])</literal> + </term> + <term> + <literal>env.SConscript(scripts, [exports, variant_dir, duplicate])</literal> + </term> + <term> + <literal>SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate])</literal> + </term> + <term> + <literal>env.SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This tells +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +to execute +one or more subsidiary SConscript (configuration) files. +Any variables returned by a called script using +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Return"><function>Return</function></link> +will be returned by the call to +<function xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</function>. +There are two ways to call the +<function xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</function> +function. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The first way you can call +<function xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</function> +is to explicitly specify one or more +<varname>scripts</varname> +as the first argument. +A single script may be specified as a string; +multiple scripts must be specified as a list +(either explicitly or as created by +a function like +<function xmlns="http://www.scons.org/dbxsd/v1.0">Split</function>). +Examples: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +SConscript('SConscript') # run SConscript in the current directory +SConscript('src/SConscript') # run SConscript in the src directory +SConscript(['src/SConscript', 'doc/SConscript']) +config = SConscript('MyConfig.py') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The second way you can call +<function xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</function> +is to specify a list of (sub)directory names +as a +<literal>dirs=</literal><varname>subdirs</varname> +keyword argument. +In this case, +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will, by default, +execute a subsidiary configuration file named +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename> +in each of the specified directories. +You may specify a name other than +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename> +by supplying an optional +<literal>name=</literal><varname>script</varname> +keyword argument. +The first three examples below have the same effect +as the first three examples above: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +SConscript(dirs='.') # run SConscript in the current directory +SConscript(dirs='src') # run SConscript in the src directory +SConscript(dirs=['src', 'doc']) +SConscript(dirs=['sub1', 'sub2'], name='MySConscript') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The optional +<varname>exports</varname> +argument provides a list of variable names or a dictionary of +named values to export to the +<varname>script(s)</varname>. +These variables are locally exported only to the specified +<varname>script(s)</varname>, +and do not affect the global pool of variables used by the +<function xmlns="http://www.scons.org/dbxsd/v1.0">Export</function> +function. +<!-- If multiple dirs are provided, each script gets a fresh export. --> +The subsidiary +<varname>script(s)</varname> +must use the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Import"><function>Import</function></link> +function to import the variables. +Examples: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +foo = SConscript('sub/SConscript', exports='env') +SConscript('dir/SConscript', exports=['env', 'variable']) +SConscript(dirs='subdir', exports='env variable') +SConscript(dirs=['one', 'two', 'three'], exports='shared_info') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the optional +<varname>variant_dir</varname> +argument is present, it causes an effect equivalent to the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-VariantDir"><function>VariantDir</function></link> +method described below. +(If +<varname>variant_dir</varname> +is not present, the +<!-- <varname>src_dir</varname> and --> +<varname>duplicate</varname> +<!-- arguments are ignored.) --> +argument is ignored.) +The +<varname>variant_dir</varname> +<!-- +and +<varname>src_dir</varname> +arguments are interpreted relative to the directory of the calling +--> +argument is interpreted relative to the directory of the calling +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename> +file. +See the description of the +<function xmlns="http://www.scons.org/dbxsd/v1.0">VariantDir</function> +function below for additional details and restrictions. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If +<varname>variant_dir</varname> +is present, +<!-- +but +<varname>src_dir</varname> +is not, +--> +the source directory is the directory in which the +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename> +file resides and the +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename> +file is evaluated as if it were in the +<varname>variant_dir</varname> +directory: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +SConscript('src/SConscript', variant_dir = 'build') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +is equivalent to +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +VariantDir('build', 'src') +SConscript('build/SConscript') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This later paradigm is often used when the sources are +in the same directory as the +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConstruct</filename>: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +SConscript('SConscript', variant_dir = 'build') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +is equivalent to +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +VariantDir('build', '.') +SConscript('build/SConscript') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<!-- +If +<varname>variant_dir</varname> +and" +<varname>src_dir</varname> +are both present, +xxxxx everything is in a state of confusion. +</para> +<example_commands> +SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.') +runs src/SConscript in build/src, but +SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src') +runs lib/SConscript (in lib!). However, +SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src') +runs src/SConscript in build. Moreover, +SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src') +runs src/lib/SConscript in build/lib. Moreover, +SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src') +can't find build/src/lib/SConscript, even though it ought to exist. +</example_commands> +<para> +is equivalent to +</para> +<example_commands> +???????????????? +</example_commands> +<para> +and what about this alternative? +TODO??? SConscript('build/SConscript', src_dir='src') +--> +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Here are some composite examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# collect the configuration information and use it to build src and doc +shared_info = SConscript('MyConfig.py') +SConscript('src/SConscript', exports='shared_info') +SConscript('doc/SConscript', exports='shared_info') +</example_commands> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# build debugging and production versions. SConscript +# can use Dir('.').path to determine variant. +SConscript('SConscript', variant_dir='debug', duplicate=0) +SConscript('SConscript', variant_dir='prod', duplicate=0) +</example_commands> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# build debugging and production versions. SConscript +# is passed flags to use. +opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' } +SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts) +opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' } +SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts) +</example_commands> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# build common documentation and compile for different architectures +SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0) +SConscript('src/SConscript', variant_dir='build/x86', duplicate=0) +SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-SConscriptChdir"> + <term> + <literal>SConscriptChdir(value)</literal> + </term> + <term> + <literal>env.SConscriptChdir(value)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +By default, +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +changes its working directory +to the directory in which each +subsidiary SConscript file lives. +This behavior may be disabled +by specifying either: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +SConscriptChdir(0) +env.SConscriptChdir(0) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +in which case +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will stay in the top-level directory +while reading all SConscript files. +(This may be necessary when building from repositories, +when all the directories in which SConscript files may be found +don't necessarily exist locally.) +You may enable and disable +this ability by calling +SConscriptChdir() +multiple times. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env = Environment() +SConscriptChdir(0) +SConscript('foo/SConscript') # will not chdir to foo +env.SConscriptChdir(1) +SConscript('bar/SConscript') # will chdir to bar +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-SConsignFile"> + <term> + <literal>SConsignFile([file, dbm_module])</literal> + </term> + <term> + <literal>env.SConsignFile([file, dbm_module])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This tells +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +to store all file signatures +in the specified database +<varname>file</varname>. +If the +<varname>file</varname> +name is omitted, +<filename>.sconsign</filename> +is used by default. +(The actual file name(s) stored on disk +may have an appropriated suffix appended +by the +<varname> dbm_module</varname>.) +If +<varname>file</varname> +is not an absolute path name, +the file is placed in the same directory as the top-level +<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConstruct</filename> +file. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If +<varname>file</varname> +is +<literal>None</literal>, +then +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will store file signatures +in a separate +<filename>.sconsign</filename> +file in each directory, +not in one global database file. +(This was the default behavior +prior to SCons 0.96.91 and 0.97.) +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The optional +<varname>dbm_module</varname> +argument can be used to specify +which Python database module +The default is to use a custom +<filename>SCons.dblite</filename> +module that uses pickled +Python data structures, +and which works on all Python versions. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# Explicitly stores signatures in ".sconsign.dblite" +# in the top-level SConstruct directory (the +# default behavior). +SConsignFile() + +# Stores signatures in the file "etc/scons-signatures" +# relative to the top-level SConstruct directory. +SConsignFile("etc/scons-signatures") + +# Stores signatures in the specified absolute file name. +SConsignFile("/home/me/SCons/signatures") + +# Stores signatures in a separate .sconsign file +# in each directory. +SConsignFile(None) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-SetDefault"> + <term> + <literal>env.SetDefault(key=val, [...])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Sets construction variables to default values specified with the keyword +arguments if (and only if) the variables are not already set. +The following statements are equivalent: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.SetDefault(FOO = 'foo') + +if 'FOO' not in env: env['FOO'] = 'foo' +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-SetOption"> + <term> + <literal>SetOption(name, value)</literal> + </term> + <term> + <literal>env.SetOption(name, value)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This function provides a way to set a select subset of the scons command +line options from a SConscript file. The options supported are: +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<variablelist> +<varlistentry> +<term><literal>clean</literal></term> +<listitem> +<para> +which corresponds to -c, --clean and --remove; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>duplicate</literal></term> +<listitem> +<para> +which corresponds to --duplicate; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>help</literal></term> +<listitem> +<para> +which corresponds to -h and --help; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>implicit_cache</literal></term> +<listitem> +<para> +which corresponds to --implicit-cache; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>max_drift</literal></term> +<listitem> +<para> +which corresponds to --max-drift; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>no_exec</literal></term> +<listitem> +<para> +which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>num_jobs</literal></term> +<listitem> +<para> +which corresponds to -j and --jobs; +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>random</literal></term> +<listitem> +<para> +which corresponds to --random; and +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>stack_size</literal></term> +<listitem> +<para> +which corresponds to --stack-size. +</para> +</listitem> +</varlistentry> +</variablelist> +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +See the documentation for the +corresponding command line object for information about each specific +option. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +SetOption('max_drift', 1) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-SideEffect"> + <term> + <literal>SideEffect(side_effect, target)</literal> + </term> + <term> + <literal>env.SideEffect(side_effect, target)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Declares +<varname>side_effect</varname> +as a side effect of building +<varname>target</varname>. +Both +<varname>side_effect</varname> +and +<varname>target</varname> +can be a list, a file name, or a node. +A side effect is a target file that is created or updated +as a side effect of building other targets. +For example, a Windows PDB +file is created as a side effect of building the .obj +files for a static library, +and various log files are created updated +as side effects of various TeX commands. +If a target is a side effect of multiple build commands, +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will ensure that only one set of commands +is executed at a time. +Consequently, you only need to use this method +for side-effect targets that are built as a result of +multiple build commands. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Because multiple build commands may update +the same side effect file, +by default the +<varname>side_effect</varname> +target is +<emphasis>not</emphasis> +automatically removed +when the +<varname>target</varname> +is removed by the +<option>-c</option> +option. +(Note, however, that the +<varname>side_effect</varname> +might be removed as part of +cleaning the directory in which it lives.) +If you want to make sure the +<varname>side_effect</varname> +is cleaned whenever a specific +<varname>target</varname> +is cleaned, +you must specify this explicitly +with the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Clean"><function>Clean</function></link> +or +<function xmlns="http://www.scons.org/dbxsd/v1.0">env.Clean</function> +function. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-SourceCode"> + <term> + <literal>SourceCode(entries, builder)</literal> + </term> + <term> + <literal>env.SourceCode(entries, builder)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This function and its associate factory functions are deprecated. +There is no replacement. +The intended use was to keep a local tree in sync with an archive, +but in actuality the function only causes the archive +to be fetched on the first run. +Synchronizing with the archive is best done external to <application xmlns="http://www.scons.org/dbxsd/v1.0">SCons</application>. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Arrange for non-existent source files to +be fetched from a source code management system +using the specified +<varname>builder</varname>. +The specified +<varname>entries</varname> +may be a Node, string or list of both, +and may represent either individual +source files or directories in which +source files can be found. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +For any non-existent source files, +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will search up the directory tree +and use the first +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function> +builder it finds. +The specified +<varname>builder</varname> +may be +<literal>None</literal>, +in which case +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will not use a builder to fetch +source files for the specified +<varname>entries</varname>, +even if a +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function> +builder has been specified +for a directory higher up the tree. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will, by default, +fetch files from SCCS or RCS subdirectories +without explicit configuration. +This takes some extra processing time +to search for the necessary +source code management files on disk. +You can avoid these extra searches +and speed up your build a little +by disabling these searches as follows: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.SourceCode('.', None) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that if the specified +<varname>builder</varname> +is one you create by hand, +it must have an associated +construction environment to use +when fetching a source file. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +provides a set of canned factory +functions that return appropriate +Builders for various popular +source code management systems. +Canonical examples of invocation include: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.SourceCode('.', env.BitKeeper('/usr/local/BKsources')) +env.SourceCode('src', env.CVS('/usr/local/CVSROOT')) +env.SourceCode('/', env.RCS()) +env.SourceCode(['f1.c', 'f2.c'], env.SCCS()) +env.SourceCode('no_source.c', None) +</example_commands> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<!-- env.SourceCode('.', env.Subversion('file:///usr/local/Subversion')) --> +</para> +</listitem> + </varlistentry> + <varlistentry id="f-SourceSignatures"> + <term> + <literal>SourceSignatures(type)</literal> + </term> + <term> + <literal>env.SourceSignatures(type)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note: Although it is not yet officially deprecated, +use of this function is discouraged. +See the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Decider"><function>Decider</function></link> +function for a more flexible and straightforward way +to configure SCons' decision-making. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function> +function tells +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +how to decide if a source file +(a file that is not built from any other files) +has changed since the last time it +was used to build a particular target file. +Legal values are +<literal>MD5</literal> +or +<literal>timestamp</literal>. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the environment method is used, +the specified type of source signature +is only used when deciding whether targets +built with that environment are up-to-date or must be rebuilt. +If the global function is used, +the specified type of source signature becomes the default +used for all decisions +about whether targets are up-to-date. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>MD5</literal> +means +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +decides that a source file has changed +if the MD5 checksum of its contents has changed since +the last time it was used to rebuild a particular target file. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>timestamp</literal> +means +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +decides that a source file has changed +if its timestamp (modification time) has changed since +the last time it was used to rebuild a particular target file. +(Note that although this is similar to the behavior of Make, +by default it will also rebuild if the dependency is +<emphasis>older</emphasis> +than the last time it was used to rebuild the target file.) +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +There is no different between the two behaviors +for Python +<function xmlns="http://www.scons.org/dbxsd/v1.0">Value</function> +node objects. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>MD5</literal> +signatures take longer to compute, +but are more accurate than +<literal>timestamp</literal> +signatures. +The default value is +<literal>MD5</literal>. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that the default +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-TargetSignatures"><function>TargetSignatures</function></link> +setting (see below) +is to use this +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function> +setting for any target files that are used +to build other target files. +Consequently, changing the value of +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function> +will, by default, +affect the up-to-date decision for all files in the build +(or all files built with a specific construction environment +when +<function xmlns="http://www.scons.org/dbxsd/v1.0">env.SourceSignatures</function> +is used). +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Split"> + <term> + <literal>Split(arg)</literal> + </term> + <term> + <literal>env.Split(arg)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Returns a list of file names or other objects. +If arg is a string, +it will be split on strings of white-space characters +within the string, +making it easier to write long lists of file names. +If arg is already a list, +the list will be returned untouched. +If arg is any other type of object, +it will be returned as a list +containing just the object. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +files = Split("f1.c f2.c f3.c") +files = env.Split("f4.c f5.c f6.c") +files = Split(""" + f7.c + f8.c + f9.c +""") +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-subst"> + <term> + <literal>env.subst(input, [raw, target, source, conv])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Performs construction variable interpolation +on the specified string or sequence argument +<varname>input</varname>. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +By default, +leading or trailing white space will +be removed from the result. +and all sequences of white space +will be compressed to a single space character. +Additionally, any +<literal>$(</literal> +and +<literal>$)</literal> +character sequences will be stripped from the returned string, +The optional +<varname>raw</varname> +argument may be set to +<literal>1</literal> +if you want to preserve white space and +<literal>$(</literal>-<literal>$)</literal> +sequences. +The +<varname>raw</varname> +argument may be set to +<literal>2</literal> +if you want to strip +all characters between +any +<literal>$(</literal> +and +<literal>$)</literal> +pairs +(as is done for signature calculation). +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the input is a sequence +(list or tuple), +the individual elements of +the sequence will be expanded, +and the results will be returned as a list. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The optional +<varname>target</varname> +and +<varname>source</varname> +keyword arguments +must be set to lists of +target and source nodes, respectively, +if you want the +<envar xmlns="http://www.scons.org/dbxsd/v1.0">$TARGET</envar>, +<envar xmlns="http://www.scons.org/dbxsd/v1.0">$TARGETS</envar>, +<envar xmlns="http://www.scons.org/dbxsd/v1.0">$SOURCE</envar> +and +<envar xmlns="http://www.scons.org/dbxsd/v1.0">$SOURCES</envar> +to be available for expansion. +This is usually necessary if you are +calling +<function xmlns="http://www.scons.org/dbxsd/v1.0">env.subst</function> +from within a Python function used +as an SCons action. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Returned string values or sequence elements +are converted to their string representation by default. +The optional +<varname>conv</varname> +argument +may specify a conversion function +that will be used in place of +the default. +For example, if you want Python objects +(including SCons Nodes) +to be returned as Python objects, +you can use the Python +Λ +idiom to pass in an unnamed function +that simply returns its unconverted argument. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +print env.subst("The C compiler is: $CC") + +def compile(target, source, env): + sourceDir = env.subst("${SOURCE.srcdir}", + target=target, + source=source) + +source_nodes = env.subst('$EXPAND_TO_NODELIST', + conv=lambda x: x) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Tag"> + <term> + <literal>Tag(node, tags)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Annotates file or directory Nodes with +information about how the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-Package"><function>Package</function></link> +Builder should package those files or directories. +All tags are optional. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# makes sure the built library will be installed with 0644 file +# access mode +Tag( Library( 'lib.c' ), UNIX_ATTR="0644" ) + +# marks file2.txt to be a documentation file +Tag( 'file2.txt', DOC ) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-TargetSignatures"> + <term> + <literal>TargetSignatures(type)</literal> + </term> + <term> + <literal>env.TargetSignatures(type)</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note: Although it is not yet officially deprecated, +use of this function is discouraged. +See the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Decider"><function>Decider</function></link> +function for a more flexible and straightforward way +to configure SCons' decision-making. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The +<function xmlns="http://www.scons.org/dbxsd/v1.0">TargetSignatures</function> +function tells +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +how to decide if a target file +(a file that +<emphasis>is</emphasis> +built from any other files) +has changed since the last time it +was used to build some other target file. +Legal values are +<literal>"build"</literal>; +<literal>"content"</literal> +(or its synonym +<literal>"MD5"</literal>); +<literal>"timestamp"</literal>; +or +<literal>"source"</literal>. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the environment method is used, +the specified type of target signature is only used +for targets built with that environment. +If the global function is used, +the specified type of signature becomes the default +used for all target files that +don't have an explicit target signature type +specified for their environments. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>"content"</literal> +(or its synonym +<literal>"MD5"</literal>) +means +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +decides that a target file has changed +if the MD5 checksum of its contents has changed since +the last time it was used to rebuild some other target file. +This means +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will open up +MD5 sum the contents +of target files after they're built, +and may decide that it does not need to rebuild +"downstream" target files if a file was +rebuilt with exactly the same contents as the last time. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>"timestamp"</literal> +means +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +decides that a target file has changed +if its timestamp (modification time) has changed since +the last time it was used to rebuild some other target file. +(Note that although this is similar to the behavior of Make, +by default it will also rebuild if the dependency is +<emphasis>older</emphasis> +than the last time it was used to rebuild the target file.) +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>"source"</literal> +means +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +decides that a target file has changed +as specified by the corresponding +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function> +setting +(<literal>"MD5"</literal> +or +<literal>"timestamp"</literal>). +This means that +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will treat all input files to a target the same way, +regardless of whether they are source files +or have been built from other files. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>"build"</literal> +means +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +decides that a target file has changed +if it has been rebuilt in this invocation +or if its content or timestamp have changed +as specified by the corresponding +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function> +setting. +This "propagates" the status of a rebuilt file +so that other "downstream" target files +will always be rebuilt, +even if the contents or the timestamp +have not changed. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>"build"</literal> +signatures are fastest because +<literal>"content"</literal> +(or +<literal>"MD5"</literal>) +signatures take longer to compute, +but are more accurate than +<literal>"timestamp"</literal> +signatures, +and can prevent unnecessary "downstream" rebuilds +when a target file is rebuilt to the exact same contents +as the previous build. +The +<literal>"source"</literal> +setting provides the most consistent behavior +when other target files may be rebuilt from +both source and target input files. +The default value is +<literal>"source"</literal>. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Because the default setting is +<literal>"source"</literal>, +using +<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function> +is generally preferable to +<function xmlns="http://www.scons.org/dbxsd/v1.0">TargetSignatures</function>, +so that the up-to-date decision +will be consistent for all files +(or all files built with a specific construction environment). +Use of +<function xmlns="http://www.scons.org/dbxsd/v1.0">TargetSignatures</function> +provides specific control for how built target files +affect their "downstream" dependencies. +</para> +</listitem> + </varlistentry> + <varlistentry id="f-Tool"> + <term> + <literal>Tool(string, [toolpath, **kw])</literal> + </term> + <term> + <literal>env.Tool(string, [toolpath, **kw])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The +<function xmlns="http://www.scons.org/dbxsd/v1.0">Tool</function> +form of the function +returns a callable object +that can be used to initialize +a construction environment using the +tools keyword of the Environment() method. +The object may be called with a construction +environment as an argument, +in which case the object will +add the necessary variables +to the construction environment +and the name of the tool will be added to the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-TOOLS"><envar>$TOOLS</envar></link> +construction variable. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Additional keyword arguments are passed to the tool's +<function>generate</function>() +method. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env = Environment(tools = [ Tool('msvc') ]) + +env = Environment() +t = Tool('msvc') +t(env) # adds 'msvc' to the TOOLS variable +u = Tool('opengl', toolpath = ['tools']) +u(env) # adds 'opengl' to the TOOLS variable +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The +<function xmlns="http://www.scons.org/dbxsd/v1.0">env.Tool</function> +form of the function +applies the callable object for the specified tool +<varname>string</varname> +to the environment through which the method was called. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Additional keyword arguments are passed to the tool's +<function>generate</function>() +method. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Tool('gcc') +env.Tool('opengl', toolpath = ['build/tools']) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-Value"> + <term> + <literal>Value(value, [built_value])</literal> + </term> + <term> + <literal>env.Value(value, [built_value])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Returns a Node object representing the specified Python value. Value +Nodes can be used as dependencies of targets. If the result of +calling +<function>str</function>(<varname>value</varname>) +changes between SCons runs, any targets depending on +<function>Value</function>(<varname>value</varname>) +will be rebuilt. +(This is true even when using timestamps to decide if +files are up-to-date.) +When using timestamp source signatures, Value Nodes' +timestamps are equal to the system time when the Node is created. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The returned Value Node object has a +<function>write</function>() +method that can be used to "build" a Value Node +by setting a new value. +The optional +<varname>built_value</varname> +argument can be specified +when the Value Node is created +to indicate the Node should already be considered +"built." +There is a corresponding +<function>read</function>() +method that will return the built value of the Node. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env = Environment() + +def create(target, source, env): + # A function that will write a 'prefix=$SOURCE' + # string into the file name specified as the + # $TARGET. + f = open(str(target[0]), 'wb') + f.write('prefix=' + source[0].get_contents()) + +# Fetch the prefix= argument, if any, from the command +# line, and use /usr/local as the default. +prefix = ARGUMENTS.get('prefix', '/usr/local') + +# Attach a .Config() builder for the above function action +# to the construction environment. +env['BUILDERS']['Config'] = Builder(action = create) +env.Config(target = 'package-config', source = Value(prefix)) + +def build_value(target, source, env): + # A function that "builds" a Python Value by updating + # the the Python value with the contents of the file + # specified as the source of the Builder call ($SOURCE). + target[0].write(source[0].get_contents()) + +output = env.Value('before') +input = env.Value('after') + +# Attach a .UpdateValue() builder for the above function +# action to the construction environment. +env['BUILDERS']['UpdateValue'] = Builder(action = build_value) +env.UpdateValue(target = Value(output), source = Value(input)) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-VariantDir"> + <term> + <literal>VariantDir(variant_dir, src_dir, [duplicate])</literal> + </term> + <term> + <literal>env.VariantDir(variant_dir, src_dir, [duplicate])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Use the +<function xmlns="http://www.scons.org/dbxsd/v1.0">VariantDir</function> +function to create a copy of your sources in another location: +if a name under +<varname>variant_dir</varname> +is not found but exists under +<varname>src_dir</varname>, +the file or directory is copied to +<varname>variant_dir</varname>. +Target files can be built in a different directory +than the original sources by simply refering to the sources (and targets) +within the variant tree. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<function xmlns="http://www.scons.org/dbxsd/v1.0">VariantDir</function> +can be called multiple times with the same +<varname>src_dir</varname> +to set up multiple builds with different options +(<varname>variants</varname>). +The +<varname>src_dir</varname> +location must be in or underneath the SConstruct file's directory, and +<varname>variant_dir</varname> +may not be underneath +<varname>src_dir</varname>. +<!-- +TODO: Can the above restrictions be clarified or relaxed? +TODO: The latter restriction is clearly not completely right; +TODO: src_dir = '.' works fine with a build dir under it. +--> +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The default behavior is for +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +to physically duplicate the source files in the variant tree. +Thus, a build performed in the variant tree is guaranteed to be identical +to a build performed in the source tree even if +intermediate source files are generated during the build, +or preprocessors or other scanners search for included files +relative to the source file, +or individual compilers or other invoked tools are hard-coded +to put derived files in the same directory as source files. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If possible on the platform, +the duplication is performed by linking rather than copying; +see also the +<option>--duplicate</option> +command-line option. +Moreover, only the files needed for the build are duplicated; +files and directories that are not used are not present in +<varname>variant_dir</varname>. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Duplicating the source tree may be disabled by setting the +<literal>duplicate</literal> +argument to +<literal>0</literal> +(zero). +This will cause +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +to invoke Builders using the path names of source files in +<varname>src_dir</varname> +and the path names of derived files within +<varname>variant_dir</varname>. +This is always more efficient than +<literal>duplicate=1</literal>, +and is usually safe for most builds +(but see above for cases that may cause problems). +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that +<function xmlns="http://www.scons.org/dbxsd/v1.0">VariantDir</function> +works most naturally with a subsidiary SConscript file. +However, you would then call the subsidiary SConscript file +not in the source directory, but in the +<varname>variant_dir</varname>, +regardless of the value of +<literal>duplicate</literal>. +This is how you tell +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +which variant of a source tree to build: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# run src/SConscript in two variant directories +VariantDir('build/variant1', 'src') +SConscript('build/variant1/SConscript') +VariantDir('build/variant2', 'src') +SConscript('build/variant2/SConscript') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +See also the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-SConscript"><function>SConscript</function></link> +function, described above, +for another way to specify a variant directory +in conjunction with calling a subsidiary SConscript file. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# use names in the build directory, not the source directory +VariantDir('build', 'src', duplicate=0) +Program('build/prog', 'build/source.c') +</example_commands> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# this builds both the source and docs in a separate subtree +VariantDir('build', '.', duplicate=0) +SConscript(dirs=['build/src','build/doc']) +</example_commands> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# same as previous example, but only uses SConscript +SConscript(dirs='src', variant_dir='build/src', duplicate=0) +SConscript(dirs='doc', variant_dir='build/doc', duplicate=0) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="f-WhereIs"> + <term> + <literal>WhereIs(program, [path, pathext, reject])</literal> + </term> + <term> + <literal>env.WhereIs(program, [path, pathext, reject])</literal> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Searches for the specified executable +<varname>program</varname>, +returning the full path name to the program +if it is found, +and returning None if not. +Searches the specified +<varname>path</varname>, +the value of the calling environment's PATH +(<literal>env['ENV']['PATH']</literal>), +or the user's current external PATH +(<literal>os.environ['PATH']</literal>) +by default. +On Windows systems, searches for executable +programs with any of the file extensions +listed in the specified +<varname>pathext</varname>, +the calling environment's PATHEXT +(<literal>env['ENV']['PATHEXT']</literal>) +or the user's current PATHEXT +(<literal>os.environ['PATHEXT']</literal>) +by default. +Will not select any +path name or names +in the specified +<varname>reject</varname> +list, if any. +</para> +</listitem> + </varlistentry> +</variablelist> |