SCons package

Module contents

Subpackages

• SCons.Node package
  • Submodules
  • SCons.Node.Alias module
  • SCons.Node.FS module
  • SCons.Node.Python module
  • Module contents
• SCons.Platform package
  • Submodules
  • SCons.Platform.aix module
  • SCons.Platform.cygwin module
  • SCons.Platform.darwin module
  • SCons.Platform.hpux module
  • SCons.Platform.irix module
  • SCons.Platform.mingw module
  • SCons.Platform.os2 module
  • SCons.Platform.posix module
  • SCons.Platform.sunos module
  • SCons.Platform.virtualenv module
  • SCons.Platform.win32 module
  • Module contents
• SCons.Scanner package
  • Submodules
  • SCons.Scanner.C module
  • SCons.Scanner.D module
  • SCons.Scanner.Dir module
  • SCons.Scanner.Fortran module
  • SCons.Scanner.IDL module
  • SCons.Scanner.LaTeX module
  • SCons.Scanner.Prog module
  • SCons.Scanner.RC module
  • SCons.Scanner.SWIG module
  • Module contents
• SCons.Script package
  • Submodules
  • SCons.Script.Interactive module
  • SCons.Script.Main module
  • SCons.Script.SConsOptions module
  • SCons.Script.SConscript module
  • Module contents
• SCons.Tool package
  • Module contents
• SCons.Variables package
  • Submodules
  • SCons.Variables.BoolVariable module
  • SCons.Variables.EnumVariable module
  • SCons.Variables.ListVariable module
  • SCons.Variables.PackageVariable module
  • SCons.Variables.PathVariable module
  • Module contents
• SCons.compat package
  • Module contents

Submodules

SCons.Action module

SCons Actions.

Information about executing any sort of action that can build one or more target Nodes (typically files) from one or more source Nodes (also typically files) given a specific Environment.

The base class here is ActionBase. The base class supplies just a few utility methods and some generic methods for displaying information about an Action in response to the various commands that control printing.

A second-level base class is _ActionAction. This extends ActionBase by providing the methods that can be used to show and perform an action. True Action objects will subclass _ActionAction; Action factory class objects will subclass ActionBase.

The heavy lifting is handled by subclasses for the different types of actions we might execute:

CommandAction CommandGeneratorAction FunctionAction ListAction

The subclasses supply the following public interface methods used by other modules:

__call__()

THE public interface, “calling” an Action object executes the command or Python function. This also takes care of printing a pre-substitution command for debugging purposes.

get_contents()

Fetches the “contents” of an Action for signature calculation plus the varlist. This is what gets checksummed to decide if a target needs to be rebuilt because its action changed.

genstring()

Returns a string representation of the Action without command substitution, but allows a CommandGeneratorAction to generate the right action based on the specified target, source and env. This is used by the Signature subsystem (through the Executor) to obtain an (imprecise) representation of the Action operation for informative purposes.

Subclasses also supply the following methods for internal use within this module:

__str__()

Returns a string approximation of the Action; no variable substitution is performed.

execute()

The internal method that really, truly, actually handles the execution of a command or Python function. This is used so that the __call__() methods can take care of displaying any pre-substitution representations, and then execute an action without worrying about the specific Actions involved.

get_presig()

Fetches the “contents” of a subclass for signature calculation. The varlist is added to this to produce the Action’s contents. TODO(?): Change this to always return bytes and not str?

strfunction()

Returns a substituted string representation of the Action. This is used by the _ActionAction.show() command to display the command/function that will be executed to generate the target(s).

There is a related independent ActionCaller class that looks like a regular Action, and which serves as a wrapper for arbitrary functions that we want to let the user specify the arguments to now, but actually execute later (when an out-of-date check determines that it’s needed to be executed, for example). Objects of this class are returned by an ActionFactory class that provides a __call__() method as a convenient way for wrapping up the functions.

SCons.Action.Action(act, *args, **kw)

A factory for action objects.

class SCons.Action.ActionBase

Bases: object

Base class for all types of action objects that can be held by other objects (Builders, Executors, etc.) This provides the common methods for manipulating and combining those actions.

batch_key(env, target, source)

genstring(target, source, env)

get_contents(target, source, env)

get_targets(env, executor)

Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used by this action.

get_varlist(target, source, env, executor=None)

no_batch_key(env, target, source)

presub_lines(env)

class SCons.Action.ActionCaller(parent, args, kw)

Bases: object

A class for delaying calling an Action function with specific (positional and keyword) arguments until the Action is actually executed.

This class looks to the rest of the world like a normal Action object, but what it’s really doing is hanging on to the arguments until we have a target, source and env to use for the expansion.

get_contents(target, source, env)

strfunction(target, source, env)

subst(s, target, source, env)

subst_args(target, source, env)

subst_kw(target, source, env)

class SCons.Action.ActionFactory(actfunc, strfunc, convert=<function ActionFactory.<lambda>>)

Bases: object

A factory class that will wrap up an arbitrary function as an SCons-executable Action object.

The real heavy lifting here is done by the ActionCaller class. We just collect the (positional and keyword) arguments that we’re called with and give them to the ActionCaller object we create, so it can hang onto them until it needs them.

class SCons.Action.CommandAction(cmd, **kw)

Bases: SCons.Action._ActionAction

Class for command-execution actions.

_get_implicit_deps_heavyweight(target, source, env, executor, icd_int)

Heavyweight dependency scanning involves scanning more than just the first entry in an action string. The exact behavior depends on the value of icd_int. Only files are taken as implicit dependencies; directories are ignored.

If icd_int is an integer value, it specifies the number of entries to scan for implicit dependencies. Action strings are also scanned after a &&. So for example, if icd_int=2 and the action string is “cd <some_dir> && $PYTHON $SCRIPT_PATH <another_path>”, the implicit dependencies would be the path to the python binary and the path to the script.

If icd_int is None, all entries are scanned for implicit dependencies.

_get_implicit_deps_lightweight(target, source, env, executor)

Lightweight dependency scanning involves only scanning the first entry in an action string, even if it contains &&.

batch_key(env, target, source)

execute(target, source, env, executor=None)

Execute a command action.

This will handle lists of commands as well as individual commands, because construction variable substitution may turn a single “command” into a list. This means that this class can actually handle lists of commands, even though that’s not how we use it externally.

genstring(target, source, env)

get_contents(target, source, env)

get_implicit_deps(target, source, env, executor=None)

Return the implicit dependencies of this action’s command line.

get_presig(target, source, env, executor=None)

Return the signature contents of this action’s command line.

This strips $(-$) and everything in between the string, since those parts don’t affect signatures.

get_targets(env, executor)

Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used by this action.

get_varlist(target, source, env, executor=None)

no_batch_key(env, target, source)

presub_lines(env)

print_cmd_line(s, target, source, env)

In python 3, and in some of our tests, sys.stdout is a String io object, and it takes unicode strings only This code assumes s is a regular string.

process(target, source, env, executor=None)

strfunction(target, source, env, executor=None)

class SCons.Action.CommandGeneratorAction(generator, kw)

Bases: SCons.Action.ActionBase

Class for command-generator actions.

_generate(target, source, env, for_signature, executor=None)

batch_key(env, target, source)

genstring(target, source, env, executor=None)

get_contents(target, source, env)

get_implicit_deps(target, source, env, executor=None)

get_presig(target, source, env, executor=None)

Return the signature contents of this action’s command line.

This strips $(-$) and everything in between the string, since those parts don’t affect signatures.

get_targets(env, executor)

Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used by this action.

get_varlist(target, source, env, executor=None)

no_batch_key(env, target, source)

presub_lines(env)

class SCons.Action.FunctionAction(execfunction, kw)

Bases: SCons.Action._ActionAction

Class for Python function actions.

batch_key(env, target, source)

execute(target, source, env, executor=None)

function_name()

genstring(target, source, env)

get_contents(target, source, env)

get_implicit_deps(target, source, env)

get_presig(target, source, env)

Return the signature contents of this callable action.

get_targets(env, executor)

Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used by this action.

get_varlist(target, source, env, executor=None)

no_batch_key(env, target, source)

presub_lines(env)

print_cmd_line(s, target, source, env)

In python 3, and in some of our tests, sys.stdout is a String io object, and it takes unicode strings only This code assumes s is a regular string.

strfunction(target, source, env, executor=None)

class SCons.Action.LazyAction(var, kw)

Bases: SCons.Action.CommandGeneratorAction, SCons.Action.CommandAction

A LazyAction is a kind of hybrid generator and command action for strings of the form “$VAR”. These strings normally expand to other strings (think “$CCCOM” to “$CC -c -o $TARGET $SOURCE”), but we also want to be able to replace them with functions in the construction environment. Consequently, we want lazy evaluation and creation of an Action in the case of the function, but that’s overkill in the more normal case of expansion to other strings.

So we do this with a subclass that’s both a generator and a command action. The overridden methods all do a quick check of the construction variable, and if it’s a string we just call the corresponding CommandAction method to do the heavy lifting. If not, then we call the same-named CommandGeneratorAction method. The CommandGeneratorAction methods work by using the overridden _generate() method, that is, our own way of handling “generation” of an action based on what’s in the construction variable.

_generate(target, source, env, for_signature, executor=None)

_generate_cache(env)

_get_implicit_deps_heavyweight(target, source, env, executor, icd_int)

Heavyweight dependency scanning involves scanning more than just the first entry in an action string. The exact behavior depends on the value of icd_int. Only files are taken as implicit dependencies; directories are ignored.

If icd_int is an integer value, it specifies the number of entries to scan for implicit dependencies. Action strings are also scanned after a &&. So for example, if icd_int=2 and the action string is “cd <some_dir> && $PYTHON $SCRIPT_PATH <another_path>”, the implicit dependencies would be the path to the python binary and the path to the script.

If icd_int is None, all entries are scanned for implicit dependencies.

_get_implicit_deps_lightweight(target, source, env, executor)

Lightweight dependency scanning involves only scanning the first entry in an action string, even if it contains &&.

batch_key(env, target, source)

execute(target, source, env, executor=None)

Execute a command action.

This will handle lists of commands as well as individual commands, because construction variable substitution may turn a single “command” into a list. This means that this class can actually handle lists of commands, even though that’s not how we use it externally.

genstring(target, source, env, executor=None)

get_contents(target, source, env)

get_implicit_deps(target, source, env, executor=None)

Return the implicit dependencies of this action’s command line.

get_parent_class(env)

get_presig(target, source, env)

Return the signature contents of this action’s command line.

This strips $(-$) and everything in between the string, since those parts don’t affect signatures.

get_targets(env, executor)

Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used by this action.

get_varlist(target, source, env, executor=None)

no_batch_key(env, target, source)

presub_lines(env)

print_cmd_line(s, target, source, env)

In python 3, and in some of our tests, sys.stdout is a String io object, and it takes unicode strings only This code assumes s is a regular string.

process(target, source, env, executor=None)

strfunction(target, source, env, executor=None)

class SCons.Action.ListAction(actionlist)

Bases: SCons.Action.ActionBase

Class for lists of other actions.

batch_key(env, target, source)

genstring(target, source, env)

get_contents(target, source, env)

get_implicit_deps(target, source, env)

get_presig(target, source, env)

Return the signature contents of this action list.

Simple concatenation of the signatures of the elements.

get_targets(env, executor)

Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used by this action.

get_varlist(target, source, env, executor=None)

no_batch_key(env, target, source)

presub_lines(env)

class SCons.Action._ActionAction(cmdstr=<class 'SCons.Action._null'>, strfunction=<class 'SCons.Action._null'>, varlist=(), presub=<class 'SCons.Action._null'>, chdir=None, exitstatfunc=None, batch_key=None, targets='$TARGETS', **kw)

Bases: SCons.Action.ActionBase

Base class for actions that create output objects.

batch_key(env, target, source)

genstring(target, source, env)

get_contents(target, source, env)

get_targets(env, executor)

Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used by this action.

get_varlist(target, source, env, executor=None)

no_batch_key(env, target, source)

presub_lines(env)

print_cmd_line(s, target, source, env)

In python 3, and in some of our tests, sys.stdout is a String io object, and it takes unicode strings only This code assumes s is a regular string.

SCons.Action._actionAppend(act1, act2)

SCons.Action._callable_contents(obj)

Return the signature contents of a callable Python object.

SCons.Action._code_contents(code, docstring=None)

Return the signature contents of a code object.

By providing direct access to the code object of the function, Python makes this extremely easy. Hooray!

Unfortunately, older versions of Python include line number indications in the compiled byte code. Boo! So we remove the line number byte codes to prevent recompilations from moving a Python function.

See:

• https://docs.python.org/2/library/inspect.html

• http://python-reference.readthedocs.io/en/latest/docs/code/index.html

For info on what each co_ variable provides

The signature is as follows (should be byte/chars): co_argcount, len(co_varnames), len(co_cellvars), len(co_freevars), ( comma separated signature for each object in co_consts ), ( comma separated signature for each object in co_names ), ( The bytecode with line number bytecodes removed from co_code )

co_argcount - Returns the number of positional arguments (including arguments with default values). co_varnames - Returns a tuple containing the names of the local variables (starting with the argument names). co_cellvars - Returns a tuple containing the names of local variables that are referenced by nested functions. co_freevars - Returns a tuple containing the names of free variables. (?) co_consts - Returns a tuple containing the literals used by the bytecode. co_names - Returns a tuple containing the names used by the bytecode. co_code - Returns a string representing the sequence of bytecode instructions.

SCons.Action._do_create_action(act, kw)

This is the actual “implementation” for the Action factory method, below. This handles the fact that passing lists to Action() itself has different semantics than passing lists as elements of lists.

The former will create a ListAction, the latter will create a CommandAction by converting the inner list elements to strings.

SCons.Action._do_create_keywords(args, kw)

This converts any arguments after the action argument into their equivalent keywords and adds them to the kw argument.

SCons.Action._do_create_list_action(act, kw)

A factory for list actions. Convert the input list into Actions and then wrap them in a ListAction.

SCons.Action._function_contents(func)

The signature is as follows (should be byte/chars): < _code_contents (see above) from func.__code__ > ,( comma separated _object_contents for function argument defaults) ,( comma separated _object_contents for any closure contents )

See also: https://docs.python.org/3/reference/datamodel.html

• func.__code__ - The code object representing the compiled function body.

• func.__defaults__ - A tuple containing default argument values for those arguments that have defaults, or None if no arguments have a default value

• func.__closure__ - None or a tuple of cells that contain bindings for the function’s free variables.

Returns

Signature contents of a function. (in bytes)

class SCons.Action._null

Bases: object

SCons.Action._object_contents(obj)

Return the signature contents of any Python object.

We have to handle the case where object contains a code object since it can be pickled directly.

SCons.Action._object_instance_content(obj)

Returns consistant content for a action class or an instance thereof

Parameters

• obj Should be either and action class or an instance thereof

Returns

bytearray or bytes representing the obj suitable for generating a signature from.

SCons.Action._resolve_shell_env(env, target, source)

First get default environment. Then if SHELL_ENV_GENERATORS is set and is iterable, call each callable in that list to allow it to alter the created execution environment.

SCons.Action._string_from_cmd_list(cmd_list)

Takes a list of command line arguments and returns a pretty representation for printing.

SCons.Action._subproc(scons_env, cmd, error='ignore', **kw)

Wrapper for subprocess which pulls from construction env.

Use for calls to subprocess which need to interpolate values from an SCons construction environment into the environment passed to subprocess. Adds an an error-handling argument. Adds ability to specify std{in,out,err} with “‘devnull’” tag.

SCons.Action.default_exitstatfunc(s)

SCons.Action.get_default_ENV(env)

A fiddlin’ little function that has an ‘import SCons.Environment’ which can’t be moved to the top level without creating an import loop. Since this import creates a local variable named ‘SCons’, it blocks access to the global variable, so we move it here to prevent complaints about local variables being used uninitialized.

SCons.Action.rfile(n)

SCons.Builder module

SCons.Builder

Builder object subsystem.

A Builder object is a callable that encapsulates information about how to execute actions to create a target Node (file) from source Nodes (files), and how to create those dependencies for tracking.

The main entry point here is the Builder() factory method. This provides a procedural interface that creates the right underlying Builder object based on the keyword arguments supplied and the types of the arguments.

The goal is for this external interface to be simple enough that the vast majority of users can create new Builders as necessary to support building new types of files in their configurations, without having to dive any deeper into this subsystem.

The base class here is BuilderBase. This is a concrete base class which does, in fact, represent the Builder objects that we (or users) create.

There is also a proxy that looks like a Builder:

CompositeBuilder

This proxies for a Builder with an action that is actually a dictionary that knows how to map file suffixes to a specific action. This is so that we can invoke different actions (compilers, compile options) for different flavors of source files.

Builders and their proxies have the following public interface methods used by other modules:

• __call__()

  THE public interface. Calling a Builder object (with the use of internal helper methods) sets up the target and source dependencies, appropriate mapping to a specific action, and the environment manipulation necessary for overridden construction variable. This also takes care of warning about possible mistakes in keyword arguments.

• add_emitter()

  Adds an emitter for a specific file suffix, used by some Tool modules to specify that (for example) a yacc invocation on a .y can create a .h and a .c file.

• add_action()

  Adds an action for a specific file suffix, heavily used by Tool modules to add their specific action(s) for turning a source file into an object file to the global static and shared object file Builders.

There are the following methods for internal use within this module:

• _execute()

  The internal method that handles the heavily lifting when a Builder is called. This is used so that the __call__() methods can set up warning about possible mistakes in keyword-argument overrides, and then execute all of the steps necessary so that the warnings only occur once.

• get_name()

  Returns the Builder’s name within a specific Environment, primarily used to try to return helpful information in error messages.

• adjust_suffix()

• get_prefix()

• get_suffix()

• get_src_suffix()

• set_src_suffix()

  Miscellaneous stuff for handling the prefix and suffix manipulation we use in turning source file names into target file names.

SCons.Builder.Builder(**kw)

A factory for builder objects.

class SCons.Builder.BuilderBase(action=None, prefix='', suffix='', src_suffix='', target_factory=None, source_factory=None, target_scanner=None, source_scanner=None, emitter=None, multi=0, env=None, single_source=0, name=None, chdir=<class 'SCons.Builder._Null'>, is_explicit=1, src_builder=None, ensure_suffix=False, **overrides)

Bases: object

Base class for Builders, objects that create output nodes (files) from input nodes (files).

_adjustixes(files, pre, suf, ensure_suffix=False)

_create_nodes(env, target=None, source=None)

Create and return lists of target and source nodes.

_execute(env, target, source, overwarn={}, executor_kw={})

_get_sdict(env)

Returns a dictionary mapping all of the source suffixes of all src_builders of this Builder to the underlying Builder that should be called first.

This dictionary is used for each target specified, so we save a lot of extra computation by memoizing it for each construction environment.

Note that this is re-computed each time, not cached, because there might be changes to one of our source Builders (or one of their source Builders, and so on, and so on…) that we can’t “see.”

The underlying methods we call cache their computed values, though, so we hope repeatedly aggregating them into a dictionary like this won’t be too big a hit. We may need to look for a better way to do this if performance data show this has turned into a significant bottleneck.

_get_src_builders_key(env)

_subst_src_suffixes_key(env)

add_emitter(suffix, emitter)

Add a suffix-emitter mapping to this Builder.

This assumes that emitter has been initialized with an appropriate dictionary type, and will throw a TypeError if not, so the caller is responsible for knowing that this is an appropriate method to call for the Builder in question.

add_src_builder(builder)

Add a new Builder to the list of src_builders.

This requires wiping out cached values so that the computed lists of source suffixes get re-calculated.

adjust_suffix(suff)

get_name(env)

Attempts to get the name of the Builder.

Look at the BUILDERS variable of env, expecting it to be a dictionary containing this Builder, and return the key of the dictionary. If there’s no key, then return a directly-configured name (if there is one) or the name of the class (by default).

get_prefix(env, sources=[])

get_src_builders(env)

Returns the list of source Builders for this Builder.

This exists mainly to look up Builders referenced as strings in the ‘BUILDER’ variable of the construction environment and cache the result.

get_src_suffix(env)

Get the first src_suffix in the list of src_suffixes.

get_suffix(env, sources=[])

set_src_suffix(src_suffix)

set_suffix(suffix)

splitext(path, env=None)

src_builder_sources(env, source, overwarn={})

src_suffixes(env)

Returns the list of source suffixes for all src_builders of this Builder.

This is essentially a recursive descent of the src_builder “tree.” (This value isn’t cached because there may be changes in a src_builder many levels deep that we can’t see.)

subst_src_suffixes(env)

The suffix list may contain construction variable expansions, so we have to evaluate the individual strings. To avoid doing this over and over, we memoize the results for each construction environment.

class SCons.Builder.CallableSelector

Bases: SCons.Util.Selector

A callable dictionary that will, in turn, call the value it finds if it can.

clear() → None.  Remove all items from od.

copy() → a shallow copy of od

fromkeys(value=None)

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

move_to_end(key, last=True)

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

pop(k[, d]) → v, remove specified key and return the corresponding

value. If key is not found, d is returned if given, otherwise KeyError is raised.

popitem(last=True)

Remove and return a (key, value) pair from the dictionary.

Pairs are returned in LIFO order if last is true or FIFO order if false.

setdefault(key, default=None)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

class SCons.Builder.CompositeBuilder(builder, cmdgen)

Bases: SCons.Util.Proxy

A Builder Proxy whose main purpose is to always have a DictCmdGenerator as its action, and to provide access to the DictCmdGenerator’s add_action() method.

__getattr__(name)

Retrieve an attribute from the wrapped object.

Raises

AttributeError – if attribute name doesn’t exist.

add_action(suffix, action)

get()

Retrieve the entire wrapped object

class SCons.Builder.DictCmdGenerator(mapping=None, source_ext_match=True)

Bases: SCons.Util.Selector

This is a callable class that can be used as a command generator function. It holds on to a dictionary mapping file suffixes to Actions. It uses that dictionary to return the proper action based on the file suffix of the source file.

add_action(suffix, action)

Add a suffix-action pair to the mapping.

clear() → None.  Remove all items from od.

copy() → a shallow copy of od

fromkeys(value=None)

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

move_to_end(key, last=True)

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

pop(k[, d]) → v, remove specified key and return the corresponding

value. If key is not found, d is returned if given, otherwise KeyError is raised.

popitem(last=True)

Remove and return a (key, value) pair from the dictionary.

Pairs are returned in LIFO order if last is true or FIFO order if false.

setdefault(key, default=None)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

src_suffixes()

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

class SCons.Builder.DictEmitter

Bases: SCons.Util.Selector

A callable dictionary that maps file suffixes to emitters. When called, it finds the right emitter in its dictionary for the suffix of the first source file, and calls that emitter to get the right lists of targets and sources to return. If there’s no emitter for the suffix in its dictionary, the original target and source are returned.

clear() → None.  Remove all items from od.

copy() → a shallow copy of od

fromkeys(value=None)

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

move_to_end(key, last=True)

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

pop(k[, d]) → v, remove specified key and return the corresponding

value. If key is not found, d is returned if given, otherwise KeyError is raised.

popitem(last=True)

Remove and return a (key, value) pair from the dictionary.

Pairs are returned in LIFO order if last is true or FIFO order if false.

setdefault(key, default=None)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

class SCons.Builder.EmitterProxy(var)

Bases: object

This is a callable class that can act as a Builder emitter. It holds on to a string that is a key into an Environment dictionary, and will look there at actual build time to see if it holds a callable. If so, we will call that as the actual emitter.

class SCons.Builder.ListEmitter(initlist=None)

Bases: collections.UserList

A callable list of emitters that calls each in sequence, returning the result.

_abc_impl = <_abc_data object>

append(item)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

copy()

count(value) → integer -- return number of occurrences of value

extend(other)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(item)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

sort(*args, **kwds)

class SCons.Builder.OverrideWarner(mapping)

Bases: collections.UserDict

A class for warning about keyword arguments that we use as overrides in a Builder call.

This class exists to handle the fact that a single Builder call can actually invoke multiple builders. This class only emits the warnings once, no matter how many Builders are invoked.

_abc_impl = <_abc_data object>

clear() → None.  Remove all items from D.

copy()

classmethod fromkeys(iterable, value=None)

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

warn()

class SCons.Builder._Null

Bases: object

SCons.Builder._node_errors(builder, env, tlist, slist)

Validate that the lists of target and source nodes are legal for this builder and environment. Raise errors or issue warnings as appropriate.

SCons.Builder._null

alias of SCons.Builder._Null

SCons.Builder.is_a_Builder(obj)

“Returns True if the specified obj is one of our Builder classes.

The test is complicated a bit by the fact that CompositeBuilder is a proxy, not a subclass of BuilderBase.

SCons.Builder.match_splitext(path, suffixes=[])

SCons.CacheDir module

CacheDir support

class SCons.CacheDir.CacheDir(path)

Bases: object

CacheDebug(fmt, target, cachefile)

_readconfig(path)

Read the cache config.

If directory or config file do not exist, create. Take advantage of Py3 capability in os.makedirs() and in file open(): just try the operation and handle failure appropriately.

Omit the check for old cache format, assume that’s old enough there will be none of those left to worry about.

Parameters

path – path to the cache directory

cachepath(node)

classmethod copy_from_cache(env, src, dst)

classmethod copy_to_cache(env, src, dst)

get_cachedir_csig(node)

property hit_ratio

is_enabled()

is_readonly()

property misses

push(node)

push_if_forced(node)

retrieve(node)

This method is called from multiple threads in a parallel build, so only do thread safe stuff here. Do thread unsafe stuff in built().

Note that there’s a special trick here with the execute flag (one that’s not normally done for other actions). Basically if the user requested a no_exec (-n) build, then SCons.Action.execute_actions is set to 0 and when any action is called, it does its showing but then just returns zero instead of actually calling the action execution operation. The problem for caching is that if the file does NOT exist in cache then the CacheRetrieveString won’t return anything to show for the task, but the Action.__call__ won’t call CacheRetrieveFunc; instead it just returns zero, which makes the code below think that the file was successfully retrieved from the cache, therefore it doesn’t do any subsequent building. However, the CacheRetrieveString didn’t print anything because it didn’t actually exist in the cache, and no more build actions will be performed, so the user just sees nothing. The fix is to tell Action.__call__ to always execute the CacheRetrieveFunc and then have the latter explicitly check SCons.Action.execute_actions itself.

SCons.CacheDir.CachePushFunc(target, source, env)

SCons.CacheDir.CacheRetrieveFunc(target, source, env)

SCons.CacheDir.CacheRetrieveString(target, source, env)

SCons.Conftest module

Autoconf-like configuration support

The purpose of this module is to define how a check is to be performed.

A context class is used that defines functions for carrying out the tests, logging and messages. The following methods and members must be present:

context.Display(msg)

Function called to print messages that are normally displayed for the user. Newlines are explicitly used. The text should also be written to the logfile!

context.Log(msg)

Function called to write to a log file.

context.BuildProg(text, ext)

Function called to build a program, using “ext” for the file extension. Must return an empty string for success, an error message for failure. For reliable test results building should be done just like an actual program would be build, using the same command and arguments (including configure results so far).

context.CompileProg(text, ext)

Function called to compile a program, using “ext” for the file extension. Must return an empty string for success, an error message for failure. For reliable test results compiling should be done just like an actual source file would be compiled, using the same command and arguments (including configure results so far).

context.AppendLIBS(lib_name_list)

Append “lib_name_list” to the value of LIBS. “lib_namelist” is a list of strings. Return the value of LIBS before changing it (any type can be used, it is passed to SetLIBS() later.)

context.PrependLIBS(lib_name_list)

Prepend “lib_name_list” to the value of LIBS. “lib_namelist” is a list of strings. Return the value of LIBS before changing it (any type can be used, it is passed to SetLIBS() later.)

context.SetLIBS(value)

Set LIBS to “value”. The type of “value” is what AppendLIBS() returned. Return the value of LIBS before changing it (any type can be used, it is passed to SetLIBS() later.)

context.headerfilename

Name of file to append configure results to, usually “confdefs.h”. The file must not exist or be empty when starting. Empty or None to skip this (some tests will not work!).

context.config_h (may be missing).

If present, must be a string, which will be filled with the contents of a config_h file.

context.vardict

Dictionary holding variables used for the tests and stores results from the tests, used for the build commands. Normally contains “CC”, “LIBS”, “CPPFLAGS”, etc.

context.havedict

Dictionary holding results from the tests that are to be used inside a program. Names often start with “HAVE_”. These are zero (feature not present) or one (feature present). Other variables may have any value, e.g., “PERLVERSION” can be a number and “SYSTEMNAME” a string.

SCons.Conftest.CheckBuilder(context, text=None, language=None)

Configure check to see if the compiler works. Note that this uses the current value of compiler and linker flags, make sure $CFLAGS, $CPPFLAGS and $LIBS are set correctly. “language” should be “C” or “C++” and is used to select the compiler. Default is “C”. “text” may be used to specify the code to be build. Returns an empty string for success, an error message for failure.

SCons.Conftest.CheckCC(context)

Configure check for a working C compiler.

This checks whether the C compiler, as defined in the $CC construction variable, can compile a C source file. It uses the current $CCCOM value too, so that it can test against non working flags.

SCons.Conftest.CheckCXX(context)

Configure check for a working CXX compiler.

This checks whether the CXX compiler, as defined in the $CXX construction variable, can compile a CXX source file. It uses the current $CXXCOM value too, so that it can test against non working flags.

SCons.Conftest.CheckDeclaration(context, symbol, includes=None, language=None)

Checks whether symbol is declared.

Use the same test as autoconf, that is test whether the symbol is defined as a macro or can be used as an r-value.

Parameters

• symbol – str the symbol to check

• includes – str Optional “header” can be defined to include a header file.

• language – str only C and C++ supported.

Returns

bool

True if the check failed, False if succeeded.

Return type

status

SCons.Conftest.CheckFunc(context, function_name, header=None, language=None)

Configure check for a function “function_name”. “language” should be “C” or “C++” and is used to select the compiler. Default is “C”. Optional “header” can be defined to define a function prototype, include a header file or anything else that comes before main(). Sets HAVE_function_name in context.havedict according to the result. Note that this uses the current value of compiler and linker flags, make sure $CFLAGS, $CPPFLAGS and $LIBS are set correctly. Returns an empty string for success, an error message for failure.

SCons.Conftest.CheckHeader(context, header_name, header=None, language=None, include_quotes=None)

Configure check for a C or C++ header file “header_name”. Optional “header” can be defined to do something before including the header file (unusual, supported for consistency). “language” should be “C” or “C++” and is used to select the compiler. Default is “C”. Sets HAVE_header_name in context.havedict according to the result. Note that this uses the current value of compiler and linker flags, make sure $CFLAGS and $CPPFLAGS are set correctly. Returns an empty string for success, an error message for failure.

SCons.Conftest.CheckLib(context, libs, func_name=None, header=None, extra_libs=None, call=None, language=None, autoadd=1, append=True)

Configure check for a C or C++ libraries “libs”. Searches through the list of libraries, until one is found where the test succeeds. Tests if “func_name” or “call” exists in the library. Note: if it exists in another library the test succeeds anyway! Optional “header” can be defined to include a header file. If not given a default prototype for “func_name” is added. Optional “extra_libs” is a list of library names to be added after “lib_name” in the build command. To be used for libraries that “lib_name” depends on. Optional “call” replaces the call to “func_name” in the test code. It must consist of complete C statements, including a trailing “;”. Both “func_name” and “call” arguments are optional, and in that case, just linking against the libs is tested. “language” should be “C” or “C++” and is used to select the compiler. Default is “C”. Note that this uses the current value of compiler and linker flags, make sure $CFLAGS, $CPPFLAGS and $LIBS are set correctly. Returns an empty string for success, an error message for failure.

SCons.Conftest.CheckMember(context, aggregate_member, header=None, language=None)

Configure check for a C or C++ member “aggregate_member”. Optional “header” can be defined to include a header file. “language” should be “C” or “C++” and is used to select the compiler. Default is “C”. Note that this uses the current value of compiler and linker flags, make sure $CFLAGS, $CPPFLAGS and $LIBS are set correctly.

Parameters

• aggregate_member – str the member to check. For example, ‘struct tm.tm_gmtoff’.

• includes – str Optional “header” can be defined to include a header file.

• language – str only C and C++ supported.

Returns the status (0 or False = Passed, True/non-zero = Failed).

SCons.Conftest.CheckProg(context, prog_name)

Configure check for a specific program.

Check whether program prog_name exists in path. If it is found, returns the path for it, otherwise returns None.

SCons.Conftest.CheckSHCC(context)

Configure check for a working shared C compiler.

This checks whether the C compiler, as defined in the $SHCC construction variable, can compile a C source file. It uses the current $SHCCCOM value too, so that it can test against non working flags.

SCons.Conftest.CheckSHCXX(context)

Configure check for a working shared CXX compiler.

This checks whether the CXX compiler, as defined in the $SHCXX construction variable, can compile a CXX source file. It uses the current $SHCXXCOM value too, so that it can test against non working flags.

SCons.Conftest.CheckType(context, type_name, fallback=None, header=None, language=None)

Configure check for a C or C++ type “type_name”. Optional “header” can be defined to include a header file. “language” should be “C” or “C++” and is used to select the compiler. Default is “C”. Sets HAVE_type_name in context.havedict according to the result. Note that this uses the current value of compiler and linker flags, make sure $CFLAGS, $CPPFLAGS and $LIBS are set correctly. Returns an empty string for success, an error message for failure.

SCons.Conftest.CheckTypeSize(context, type_name, header=None, language=None, expect=None)

This check can be used to get the size of a given type, or to check whether the type is of expected size.

Parameters

• type (-) – str the type to check

• includes (-) – sequence list of headers to include in the test code before testing the type

• language (-) – str ‘C’ or ‘C++’

• expect (-) – int if given, will test wether the type has the given number of bytes. If not given, will automatically find the size.

• Returns –

  statusint

  0 if the check failed, or the found size of the type if the check succeeded.

SCons.Conftest._Have(context, key, have, comment=None)

Store result of a test in context.havedict and context.headerfilename.

Parameters

• key - is a “HAVE_abc” name. It is turned into all CAPITALS and non-alphanumerics are replaced by an underscore.

• have - value as it should appear in the header file, include quotes when desired and escape special characters!

• comment is the C comment to add above the line defining the symbol (the comment is automatically put inside a /* */). If None, no comment is added.

The value of “have” can be:

• 1 - Feature is defined, add “#define key”.

• 0 - Feature is not defined, add “/* #undef key */”. Adding “undef” is what autoconf does. Not useful for the compiler, but it shows that the test was done.

• number - Feature is defined to this number “#define key have”. Doesn’t work for 0 or 1, use a string then.

• string - Feature is defined to this string “#define key have”.

SCons.Conftest._LogFailed(context, text, msg)

Write to the log about a failed program. Add line numbers, so that error messages can be understood.

SCons.Conftest._YesNoResult(context, ret, key, text, comment=None)

Handle the result of a test with a “yes” or “no” result.

Parameters

• ret is the return value: empty if OK, error message when not.

• key is the name of the symbol to be defined (HAVE_foo).

• text is the source code of the program used for testing.

• comment is the C comment to add above the line defining the symbol (the comment is automatically put inside a /* */). If None, no comment is added.

SCons.Conftest._check_empty_program(context, comp, text, language, use_shared=False)

Return 0 on success, 1 otherwise.

SCons.Conftest._lang2suffix(lang)

Convert a language name to a suffix. When “lang” is empty or None C is assumed. Returns a tuple (lang, suffix, None) when it works. For an unrecognized language returns (None, None, msg).

Where:

• lang = the unified language name

• suffix = the suffix, including the leading dot

• msg = an error message

SCons.Debug module

Code for debugging SCons internal things.

Shouldn’t be needed by most users. Quick shortcuts:

from SCons.Debug import caller_trace caller_trace()

SCons.Debug.Trace(msg, tracefile=None, mode='w', tstamp=False)

Write a trace message.

Write messages when debugging which do not interfere with stdout. Useful in tests, which monitor stdout and would break with unexpected output. Trace messages can go to the console (which is opened as a file), or to a disk file; the tracefile argument persists across calls unless overridden.

Parameters

• tracefile – file to write trace message to. If omitted, write to the previous trace file (default: console).

• mode – file open mode (default: ‘w’)

• tstamp – write relative timestamps with trace. Outputs time since scons was started, and time since last trace (default: False)

SCons.Debug._dump_one_caller(key, file, level=0)

SCons.Debug.caller_stack()

return caller’s stack

SCons.Debug.caller_trace(back=0)

Trace caller stack and save info into global dicts, which are printed automatically at the end of SCons execution.

SCons.Debug.countLoggedInstances(classes, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

SCons.Debug.dumpLoggedInstances(classes, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

SCons.Debug.dump_caller_counts(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

SCons.Debug.fetchLoggedInstances(classes='*')

SCons.Debug.func_shorten(func_tuple)

SCons.Debug.listLoggedInstances(classes, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

SCons.Debug.logInstanceCreation(instance, name=None)

SCons.Debug.memory()

SCons.Debug.string_to_classes(s)

SCons.Defaults module

Builders and other things for the local site.

Here’s where we’ll duplicate the functionality of autoconf until we move it into the installation procedure or use something like qmconf.

The code that reads the registry to find MSVC components was borrowed from distutils.msvccompiler.

SCons.Defaults.DefaultEnvironment(*args, **kw)

Initial public entry point for creating the default construction Environment.

After creating the environment, we overwrite our name (DefaultEnvironment) with the _fetch_DefaultEnvironment() function, which more efficiently returns the initialized default construction environment without checking for its existence.

(This function still exists with its _default_check because someone else (cough Script/__init__.py cough) may keep a reference to this function. So we can’t use the fully functional idiom of having the name originally be a something that only creates the construction environment and then overwrites the name.)

class SCons.Defaults.NullCmdGenerator(cmd)

Bases: object

This is a callable class that can be used in place of other command generators if you don’t want them to do anything.

The __call__ method for this class simply returns the thing you instantiated it with.

Example usage: env[“DO_NOTHING”] = NullCmdGenerator env[“LINKCOM”] = “${DO_NOTHING(‘$LINK $SOURCES $TARGET’)}”

SCons.Defaults.SharedFlagChecker(source, target, env)

SCons.Defaults.SharedObjectEmitter(target, source, env)

SCons.Defaults.StaticObjectEmitter(target, source, env)

class SCons.Defaults.Variable_Method_Caller(variable, method)

Bases: object

A class for finding a construction variable on the stack and calling one of its methods.

We use this to support “construction variables” in our string eval()s that actually stand in for methods–specifically, use of “RDirs” in call to _concat that should actually execute the “TARGET.RDirs” method. (We used to support this by creating a little “build dictionary” that mapped RDirs to the method, but this got in the way of Memoizing construction environments, because we had to create new environment objects to hold the variables.)

SCons.Defaults.__lib_either_version_flag(env, version_var1, version_var2, flags_var)

if $version_var1 or $version_var2 is not empty, returns env[flags_var], otherwise returns None :param env: :param version_var1: :param version_var2: :param flags_var: :return:

SCons.Defaults.__libversionflags(env, version_var, flags_var)

if version_var is not empty, returns env[flags_var], otherwise returns None :param env: :param version_var: :param flags_var: :return:

SCons.Defaults._concat(prefix, items_iter, suffix, env, f=<function <lambda>>, target=None, source=None, affect_signature=True)

Creates a new list from ‘items_iter’ by first interpolating each element in the list using the ‘env’ dictionary and then calling f on the list, and finally calling _concat_ixes to concatenate ‘prefix’ and ‘suffix’ onto each element of the list.

SCons.Defaults._concat_ixes(prefix, items_iter, suffix, env)

Creates a new list from ‘items_iter’ by concatenating the ‘prefix’ and ‘suffix’ arguments onto each element of the list. A trailing space on ‘prefix’ or leading space on ‘suffix’ will cause them to be put into separate list elements rather than being concatenated.

SCons.Defaults._defines(prefix, defs, suffix, env, target=None, source=None, c=<function _concat_ixes>)

A wrapper around _concat_ixes that turns a list or string into a list of C preprocessor command-line definitions.

SCons.Defaults._fetch_DefaultEnvironment(*args, **kw)

Returns the already-created default construction environment.

SCons.Defaults._stripixes(prefix, itms, suffix, stripprefixes, stripsuffixes, env, c=None)

This is a wrapper around _concat()/_concat_ixes() that checks for the existence of prefixes or suffixes on list items and strips them where it finds them. This is used by tools (like the GNU linker) that need to turn something like ‘libfoo.a’ into ‘-lfoo’.

SCons.Defaults.chmod_func(dest, mode)

SCons.Defaults.chmod_strfunc(dest, mode)

SCons.Defaults.copy_func(dest, src, symlinks=True)

If symlinks (is true), then a symbolic link will be shallow copied and recreated as a symbolic link; otherwise, copying a symbolic link will be equivalent to copying the symbolic link’s final target regardless of symbolic link depth.

SCons.Defaults.delete_func(dest, must_exist=0)

SCons.Defaults.delete_strfunc(dest, must_exist=0)

SCons.Defaults.get_paths_str(dest)

SCons.Defaults.mkdir_func(dest)

SCons.Defaults.move_func(dest, src)

SCons.Defaults.processDefines(defs)

process defines, resolving strings, lists, dictionaries, into a list of strings

SCons.Defaults.touch_func(dest)

SCons.Environment module

Base class for construction Environments.

These are the primary objects used to communicate dependency and construction information to the build engine.

Keyword arguments supplied when the construction Environment is created are construction variables used to initialize the Environment.

class SCons.Environment.Base(platform=None, tools=None, toolpath=None, variables=None, parse_flags=None, **kw)

Bases: SCons.Environment.SubstitutionEnvironment

Base class for “real” construction Environments.

These are the primary objects used to communicate dependency and construction information to the build engine.

Keyword arguments supplied when the construction Environment is created are construction variables used to initialize the Environment.

Action(*args, **kw)

AddMethod(function, name=None)

Adds the specified function as a method of this construction environment with the specified name. If the name is omitted, the default name is the name of the function itself.

AddPostAction(files, action)

AddPreAction(files, action)

Alias(target, source=[], action=None, **kw)

AlwaysBuild(*targets)

Append(**kw)

Append values to construction variables in an Environment.

The variable is created if it is not already present.

AppendENVPath(name, newpath, envname='ENV', sep=':', delete_existing=False)

Append path elements to the path name in the envname dictionary for this environment. Will only add any particular path once, and will normpath and normcase all paths to help assure this. This can also handle the case where the env variable is a list instead of a string.

If delete_existing is False, a newpath element already in the path will not be moved to the end (it will be left where it is).

AppendUnique(delete_existing=False, **kw)

Append values to existing construction variables in an Environment, if they’re not already there. If delete_existing is True, removes existing values first, so values move to end.

Builder(**kw)

CacheDir(path, custom_class=None)

Clean(targets, files)

Clone(tools=[], toolpath=None, parse_flags=None, **kw)

Return a copy of a construction Environment.

The copy is like a Python “deep copy”–that is, independent copies are made recursively of each objects–except that a reference is copied when an object is not deep-copyable (like a function). There are no references to any mutable objects in the original Environment.

Command(target, source, action, **kw)

Builds the supplied target files from the supplied source files using the supplied action. Action may be any type that the Builder constructor will accept for an action.

Configure(*args, **kw)

Decider(function)

Depends(target, dependency)

Explicity specify that ‘target’s depend on ‘dependency’.

Detect(progs)

Return the first available program from one or more possibilities.

Parameters

progs (str or list) – one or more command names to check for

Dictionary(*args)

Return construction variables from an environment.

Parameters

*args (optional) – variable names to look up

Returns

If args omitted, the dictionary of all construction variables. If one arg, the corresponding value is returned. If more than one arg, a list of values is returned.

Raises

KeyError – if any of args is not in the construction environment.

Dir(name, *args, **kw)

Dump(key=None, format='pretty')

Return construction variables serialized to a string.

Parameters

• key (optional) – if None, format the whole dict of variables. Else format the value of key (Default value = None)

• format (str, optional) – specify the format to serialize to. “pretty” generates a pretty-printed string, “json” a JSON-formatted string. (Default value = “pretty”)

Entry(name, *args, **kw)

Environment(**kw)

Execute(action, *args, **kw)

Directly execute an action through an Environment

File(name, *args, **kw)

FindFile(file, dirs)

FindInstalledFiles()

returns the list of all targets of the Install and InstallAs Builder.

FindIxes(paths, prefix, suffix)

Search a list of paths for something that matches the prefix and suffix.

Parameters

• paths – the list of paths or nodes.

• prefix – construction variable for the prefix.

• suffix – construction variable for the suffix.

Returns: the matched path or None

FindSourceFiles(node='.')

returns a list of all source files.

Flatten(sequence)

GetBuildPath(files)

Glob(pattern, ondisk=True, source=False, strings=False, exclude=None)

Ignore(target, dependency)

Ignore a dependency.

Literal(string)

Local(*targets)

MergeFlags(args, unique=True) → None

Merge flags into construction variables.

Merges the flags from args into this construction environent. If args is not a dict, it is first converted to one with flags distributed into appropriate construction variables. See ParseFlags().

Parameters

• args – flags to merge

• unique – merge flags rather than appending (default: True). When merging, path variables are retained from the front, other construction variables from the end.

NoCache(*targets)

Tags a target so that it will not be cached

NoClean(*targets)

Tags a target so that it will not be cleaned by -c

Override(overrides)

Produce a modified environment whose variables are overridden by the overrides dictionaries. “overrides” is a dictionary that will override the variables of this environment.

This function is much more efficient than Clone() or creating a new Environment because it doesn’t copy the construction environment dictionary, it just wraps the underlying construction environment, and doesn’t even create a wrapper object if there are no overrides.

ParseConfig(command, function=None, unique=True)

Parse the result of running a command to update construction vars.

Use function to parse the output of running command in order to modify the current environment.

Parameters

• command – a string or a list of strings representing a command and its arguments.

• function – called to process the result of command, which will be passed as args. If function is omitted or None, MergeFlags() is used. Takes 3 args (env, args, unique)

• unique – whether no duplicate values are allowed (default true)

ParseDepends(filename, must_exist=None, only_one=False)

Parse a mkdep-style file for explicit dependencies. This is completely abusable, and should be unnecessary in the “normal” case of proper SCons configuration, but it may help make the transition from a Make hierarchy easier for some people to swallow. It can also be genuinely useful when using a tool that can write a .d file, but for which writing a scanner would be too complicated.

ParseFlags(*flags) → dict

Return a dict of parsed flags.

Parse flags and return a dict with the flags distributed into the appropriate construction variable names. The flags are treated as a typical set of command-line flags for a GNU-style toolchain, such as might have been generated by one of the {foo}-config scripts, and used to populate the entries based on knowledge embedded in this method - the choices are not expected to be portable to other toolchains.

If one of the flags strings begins with a bang (exclamation mark), it is assumed to be a command and the rest of the string is executed; the result of that evaluation is then added to the dict.

Platform(platform)

Precious(*targets)

Prepend(**kw)

Prepend values to construction variables in an Environment.

The variable is created if it is not already present.

PrependENVPath(name, newpath, envname='ENV', sep=':', delete_existing=True)

Prepend path elements to the path name in the envname dictionary for this environment. Will only add any particular path once, and will normpath and normcase all paths to help assure this. This can also handle the case where the env variable is a list instead of a string.

If delete_existing is False, a newpath component already in the path will not be moved to the front (it will be left where it is).

PrependUnique(delete_existing=False, **kw)

Prepend values to existing construction variables in an Environment, if they’re not already there. If delete_existing is True, removes existing values first, so values move to front.

Pseudo(*targets)

PyPackageDir(modulename)

RemoveMethod(function)

Removes the specified function’s MethodWrapper from the added_methods list, so we don’t re-bind it when making a clone.

Replace(**kw)

Replace existing construction variables in an Environment with new construction variables and/or values.

ReplaceIxes(path, old_prefix, old_suffix, new_prefix, new_suffix)

Replace old_prefix with new_prefix and old_suffix with new_suffix.

env - Environment used to interpolate variables. path - the path that will be modified. old_prefix - construction variable for the old prefix. old_suffix - construction variable for the old suffix. new_prefix - construction variable for the new prefix. new_suffix - construction variable for the new suffix.

Repository(*dirs, **kw)

Requires(target, prerequisite)

Specify that ‘prerequisite’ must be built before ‘target’, (but ‘target’ does not actually depend on ‘prerequisite’ and need not be rebuilt if it changes).

SConsignFile(name='.sconsign', dbm_module=None)

Scanner(*args, **kw)

SetDefault(**kw)

SideEffect(side_effect, target)

Tell scons that side_effects are built as side effects of building targets.

Split(arg)

This function converts a string or list into a list of strings or Nodes. This makes things easier for users by allowing files to be specified as a white-space separated list to be split.

The input rules are:

• A single string containing names separated by spaces. These will be split apart at the spaces.

• A single Node instance

• A list containing either strings or Node instances. Any strings in the list are not split at spaces.

In all cases, the function returns a list of Nodes and strings.

Tool(tool, toolpath=None, **kwargs) → SCons.Tool.Tool

Value(value, built_value=None, name=None)

VariantDir(variant_dir, src_dir, duplicate=1)

WhereIs(prog, path=None, pathext=None, reject=None)

Find prog in the path.

_canonicalize(path)

Allow Dirs and strings beginning with # for top-relative.

Note this uses the current env’s fs (in self).

_changed_build(dependency, target, prev_ni, repo_node=None)

_changed_content(dependency, target, prev_ni, repo_node=None)

_changed_source(dependency, target, prev_ni, repo_node=None)

_changed_timestamp_match(dependency, target, prev_ni, repo_node=None)

_changed_timestamp_newer(dependency, target, prev_ni, repo_node=None)

_changed_timestamp_then_content(dependency, target, prev_ni, repo_node=None)

_find_toolpath_dir(tp)

_gsm()

_init_special()

Initial the dispatch tables for special handling of special construction variables.

_update(other)

Private method to update an environment’s consvar dict directly.

Bypasses the normal checks that occur when users try to set items.

_update_onlynew(other)

Private method to add new items to an environment’s consvar dict.

Only adds items from other whose keys do not already appear in the existing dict; values from other are not used for replacement. Bypasses the normal checks that occur when users try to set items.

arg2nodes(args, node_factory=<class 'SCons.Environment._Null'>, lookup_list=<class 'SCons.Environment._Null'>, **kw)

backtick(command) → str

Emulate command substitution.

Provides behavior conceptually like POSIX Shell notation for running a command in backquotes (backticks) by running command and returning the resulting output string.

This is not really a public API any longer, it is provided for the use of ParseFlags() (which supports it using a syntax of !command) and ParseConfig().

Raises

OSError – if the external command returned non-zero exit status.

get(key, default=None)

Emulates the get() method of dictionaries.

get_CacheDir()

get_builder(name)

Fetch the builder with the specified name from the environment.

get_factory(factory, default='File')

Return a factory function for creating Nodes for this construction environment.

get_scanner(skey)

Find the appropriate scanner given a key (usually a file suffix).

get_src_sig_type()

get_tgt_sig_type()

gvars()

items()

Emulates the items() method of dictionaries.

keys()

Emulates the keys() method of dictionaries.

lvars()

scanner_map_delete(kw=None)

Delete the cached scanner map (if we need to).

setdefault(key, default=None)

Emulates the setdefault() method of dictionaries.

subst(string, raw=0, target=None, source=None, conv=None, executor=None)

Recursively interpolates construction variables from the Environment into the specified string, returning the expanded result. Construction variables are specified by a $ prefix in the string and begin with an initial underscore or alphabetic character followed by any number of underscores or alphanumeric characters. The construction variable names may be surrounded by curly braces to separate the name from trailing characters.

subst_kw(kw, raw=0, target=None, source=None)

subst_list(string, raw=0, target=None, source=None, conv=None, executor=None)

Calls through to SCons.Subst.scons_subst_list(). See the documentation for that function.

subst_path(path, target=None, source=None)

Substitute a path list, turning EntryProxies into Nodes and leaving Nodes (and other objects) as-is.

subst_target_source(string, raw=0, target=None, source=None, conv=None, executor=None)

Recursively interpolates construction variables from the Environment into the specified string, returning the expanded result. Construction variables are specified by a $ prefix in the string and begin with an initial underscore or alphabetic character followed by any number of underscores or alphanumeric characters. The construction variable names may be surrounded by curly braces to separate the name from trailing characters.

validate_CacheDir_class(custom_class=None)

Validate the passed custom CacheDir class, or if no args are passed, validate the custom CacheDir class from the environment.

values()

Emulates the values() method of dictionaries.

class SCons.Environment.BuilderDict(mapping, env)

Bases: collections.UserDict

This is a dictionary-like class used by an Environment to hold the Builders. We need to do this because every time someone changes the Builders in the Environment’s BUILDERS dictionary, we must update the Environment’s attributes.

_abc_impl = <_abc_data object>

clear() → None.  Remove all items from D.

copy()

classmethod fromkeys(iterable, value=None)

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

class SCons.Environment.BuilderWrapper(obj, method, name=None)

Bases: SCons.Util.MethodWrapper

A MethodWrapper subclass that that associates an environment with a Builder.

This mainly exists to wrap the __call__() function so that all calls to Builders can have their argument lists massaged in the same way (treat a lone argument as the source, treat two arguments as target then source, make sure both target and source are lists) without having to have cut-and-paste code to do it.

As a bit of obsessive backwards compatibility, we also intercept attempts to get or set the “env” or “builder” attributes, which were the names we used before we put the common functionality into the MethodWrapper base class. We’ll keep this around for a while in case people shipped Tool modules that reached into the wrapper (like the Tool/qt.py module does, or did). There shouldn’t be a lot attribute fetching or setting on these, so a little extra work shouldn’t hurt.

clone(new_object)

Returns an object that re-binds the underlying “method” to the specified new object.

SCons.Environment.NoSubstitutionProxy(subject)

An entry point for returning a proxy subclass instance that overrides the subst*() methods so they don’t actually perform construction variable substitution. This is specifically intended to be the shim layer in between global function calls (which don’t want construction variable substitution) and the DefaultEnvironment() (which would substitute variables if left to its own devices).

We have to wrap this in a function that allows us to delay definition of the class until it’s necessary, so that when it subclasses Environment it will pick up whatever Environment subclass the wrapper interface might have assigned to SCons.Environment.Environment.

class SCons.Environment.OverrideEnvironment(subject, overrides=None)

Bases: SCons.Environment.Base

A proxy that overrides variables in a wrapped construction environment by returning values from an overrides dictionary in preference to values from the underlying subject environment.

This is a lightweight (I hope) proxy that passes through most use of attributes to the underlying Environment.Base class, but has just enough additional methods defined to act like a real construction environment with overridden values. It can wrap either a Base construction environment, or another OverrideEnvironment, which can in turn nest arbitrary OverrideEnvironments…

Note that we do not call the underlying base class (SubsitutionEnvironment) initialization, because we get most of those from proxying the attributes of the subject construction environment. But because we subclass SubstitutionEnvironment, this class also has inherited arg2nodes() and subst*() methods; those methods can’t be proxied because they need this object’s methods to fetch the values from the overrides dictionary.

Action(*args, **kw)

AddMethod(function, name=None)

Adds the specified function as a method of this construction environment with the specified name. If the name is omitted, the default name is the name of the function itself.

AddPostAction(files, action)

AddPreAction(files, action)

Alias(target, source=[], action=None, **kw)

AlwaysBuild(*targets)

Append(**kw)

Append values to construction variables in an Environment.

The variable is created if it is not already present.

AppendENVPath(name, newpath, envname='ENV', sep=':', delete_existing=False)

Append path elements to the path name in the envname dictionary for this environment. Will only add any particular path once, and will normpath and normcase all paths to help assure this. This can also handle the case where the env variable is a list instead of a string.

If delete_existing is False, a newpath element already in the path will not be moved to the end (it will be left where it is).

AppendUnique(delete_existing=False, **kw)

Append values to existing construction variables in an Environment, if they’re not already there. If delete_existing is True, removes existing values first, so values move to end.

Builder(**kw)

CacheDir(path, custom_class=None)

Clean(targets, files)

Clone(tools=[], toolpath=None, parse_flags=None, **kw)

Return a copy of a construction Environment.

The copy is like a Python “deep copy”–that is, independent copies are made recursively of each objects–except that a reference is copied when an object is not deep-copyable (like a function). There are no references to any mutable objects in the original Environment.

Command(target, source, action, **kw)

Builds the supplied target files from the supplied source files using the supplied action. Action may be any type that the Builder constructor will accept for an action.

Configure(*args, **kw)

Decider(function)

Depends(target, dependency)

Explicity specify that ‘target’s depend on ‘dependency’.

Detect(progs)

Return the first available program from one or more possibilities.

Parameters

progs (str or list) – one or more command names to check for

Dictionary(*args)

Return construction variables from an environment.

Parameters

*args (optional) – variable names to look up

Returns

If args omitted, the dictionary of all construction variables. If one arg, the corresponding value is returned. If more than one arg, a list of values is returned.

Raises

KeyError – if any of args is not in the construction environment.

Dir(name, *args, **kw)

Dump(key=None, format='pretty')

Return construction variables serialized to a string.

Parameters

• key (optional) – if None, format the whole dict of variables. Else format the value of key (Default value = None)

• format (str, optional) – specify the format to serialize to. “pretty” generates a pretty-printed string, “json” a JSON-formatted string. (Default value = “pretty”)

Entry(name, *args, **kw)

Environment(**kw)

Execute(action, *args, **kw)

Directly execute an action through an Environment

File(name, *args, **kw)

FindFile(file, dirs)

FindInstalledFiles()

returns the list of all targets of the Install and InstallAs Builder.

FindIxes(paths, prefix, suffix)

Search a list of paths for something that matches the prefix and suffix.

Parameters

• paths – the list of paths or nodes.

• prefix – construction variable for the prefix.

• suffix – construction variable for the suffix.

Returns: the matched path or None

FindSourceFiles(node='.')

returns a list of all source files.

Flatten(sequence)

GetBuildPath(files)

Glob(pattern, ondisk=True, source=False, strings=False, exclude=None)

Ignore(target, dependency)

Ignore a dependency.

Literal(string)

Local(*targets)

MergeFlags(args, unique=True) → None

Merge flags into construction variables.

Merges the flags from args into this construction environent. If args is not a dict, it is first converted to one with flags distributed into appropriate construction variables. See ParseFlags().

Parameters

• args – flags to merge

• unique – merge flags rather than appending (default: True). When merging, path variables are retained from the front, other construction variables from the end.

NoCache(*targets)

Tags a target so that it will not be cached

NoClean(*targets)

Tags a target so that it will not be cleaned by -c

Override(overrides)

Produce a modified environment whose variables are overridden by the overrides dictionaries. “overrides” is a dictionary that will override the variables of this environment.

This function is much more efficient than Clone() or creating a new Environment because it doesn’t copy the construction environment dictionary, it just wraps the underlying construction environment, and doesn’t even create a wrapper object if there are no overrides.

ParseConfig(command, function=None, unique=True)

Parse the result of running a command to update construction vars.

Use function to parse the output of running command in order to modify the current environment.

Parameters

• command – a string or a list of strings representing a command and its arguments.

• function – called to process the result of command, which will be passed as args. If function is omitted or None, MergeFlags() is used. Takes 3 args (env, args, unique)

• unique – whether no duplicate values are allowed (default true)

ParseDepends(filename, must_exist=None, only_one=False)

Parse a mkdep-style file for explicit dependencies. This is completely abusable, and should be unnecessary in the “normal” case of proper SCons configuration, but it may help make the transition from a Make hierarchy easier for some people to swallow. It can also be genuinely useful when using a tool that can write a .d file, but for which writing a scanner would be too complicated.

ParseFlags(*flags) → dict

Return a dict of parsed flags.

Parse flags and return a dict with the flags distributed into the appropriate construction variable names. The flags are treated as a typical set of command-line flags for a GNU-style toolchain, such as might have been generated by one of the {foo}-config scripts, and used to populate the entries based on knowledge embedded in this method - the choices are not expected to be portable to other toolchains.

If one of the flags strings begins with a bang (exclamation mark), it is assumed to be a command and the rest of the string is executed; the result of that evaluation is then added to the dict.

Platform(platform)

Precious(*targets)

Prepend(**kw)

Prepend values to construction variables in an Environment.

The variable is created if it is not already present.

PrependENVPath(name, newpath, envname='ENV', sep=':', delete_existing=True)

Prepend path elements to the path name in the envname dictionary for this environment. Will only add any particular path once, and will normpath and normcase all paths to help assure this. This can also handle the case where the env variable is a list instead of a string.

If delete_existing is False, a newpath component already in the path will not be moved to the front (it will be left where it is).

PrependUnique(delete_existing=False, **kw)

Prepend values to existing construction variables in an Environment, if they’re not already there. If delete_existing is True, removes existing values first, so values move to front.

Pseudo(*targets)

PyPackageDir(modulename)

RemoveMethod(function)

Removes the specified function’s MethodWrapper from the added_methods list, so we don’t re-bind it when making a clone.

Replace(**kw)

Replace existing construction variables in an Environment with new construction variables and/or values.

ReplaceIxes(path, old_prefix, old_suffix, new_prefix, new_suffix)

Replace old_prefix with new_prefix and old_suffix with new_suffix.

env - Environment used to interpolate variables. path - the path that will be modified. old_prefix - construction variable for the old prefix. old_suffix - construction variable for the old suffix. new_prefix - construction variable for the new prefix. new_suffix - construction variable for the new suffix.

Repository(*dirs, **kw)

Requires(target, prerequisite)

Specify that ‘prerequisite’ must be built before ‘target’, (but ‘target’ does not actually depend on ‘prerequisite’ and need not be rebuilt if it changes).

SConsignFile(name='.sconsign', dbm_module=None)

Scanner(*args, **kw)

SetDefault(**kw)

SideEffect(side_effect, target)

Tell scons that side_effects are built as side effects of building targets.

Split(arg)

This function converts a string or list into a list of strings or Nodes. This makes things easier for users by allowing files to be specified as a white-space separated list to be split.

The input rules are:

• A single string containing names separated by spaces. These will be split apart at the spaces.

• A single Node instance

• A list containing either strings or Node instances. Any strings in the list are not split at spaces.

In all cases, the function returns a list of Nodes and strings.

Tool(tool, toolpath=None, **kwargs) → SCons.Tool.Tool

Value(value, built_value=None, name=None)

VariantDir(variant_dir, src_dir, duplicate=1)

WhereIs(prog, path=None, pathext=None, reject=None)

Find prog in the path.

_canonicalize(path)

Allow Dirs and strings beginning with # for top-relative.

Note this uses the current env’s fs (in self).

_changed_build(dependency, target, prev_ni, repo_node=None)

_changed_content(dependency, target, prev_ni, repo_node=None)

_changed_source(dependency, target, prev_ni, repo_node=None)

_changed_timestamp_match(dependency, target, prev_ni, repo_node=None)

_changed_timestamp_newer(dependency, target, prev_ni, repo_node=None)

_changed_timestamp_then_content(dependency, target, prev_ni, repo_node=None)

_find_toolpath_dir(tp)

_gsm()

_init_special()

Initial the dispatch tables for special handling of special construction variables.

_update(other)

Private method to update an environment’s consvar dict directly.

Bypasses the normal checks that occur when users try to set items.

_update_onlynew(other)

Update a dict with new keys.

Unlike the .update method, if the key is already present, it is not replaced.

arg2nodes(args, node_factory=<class 'SCons.Environment._Null'>, lookup_list=<class 'SCons.Environment._Null'>, **kw)

backtick(command) → str

Emulate command substitution.

Provides behavior conceptually like POSIX Shell notation for running a command in backquotes (backticks) by running command and returning the resulting output string.

This is not really a public API any longer, it is provided for the use of ParseFlags() (which supports it using a syntax of !command) and ParseConfig().

Raises

OSError – if the external command returned non-zero exit status.

get(key, default=None)

Emulates the get() method of dictionaries.

get_CacheDir()

get_builder(name)

Fetch the builder with the specified name from the environment.

get_factory(factory, default='File')

Return a factory function for creating Nodes for this construction environment.

get_scanner(skey)

Find the appropriate scanner given a key (usually a file suffix).

get_src_sig_type()

get_tgt_sig_type()

gvars()

items()

Emulates the items() method of dictionaries.

keys()

Emulates the keys() method of dictionaries.

lvars()

scanner_map_delete(kw=None)

Delete the cached scanner map (if we need to).

setdefault(key, default=None)

Emulates the setdefault() method of dictionaries.

subst(string, raw=0, target=None, source=None, conv=None, executor=None)

Recursively interpolates construction variables from the Environment into the specified string, returning the expanded result. Construction variables are specified by a $ prefix in the string and begin with an initial underscore or alphabetic character followed by any number of underscores or alphanumeric characters. The construction variable names may be surrounded by curly braces to separate the name from trailing characters.

subst_kw(kw, raw=0, target=None, source=None)

subst_list(string, raw=0, target=None, source=None, conv=None, executor=None)

Calls through to SCons.Subst.scons_subst_list(). See the documentation for that function.

subst_path(path, target=None, source=None)

Substitute a path list, turning EntryProxies into Nodes and leaving Nodes (and other objects) as-is.

subst_target_source(string, raw=0, target=None, source=None, conv=None, executor=None)

Recursively interpolates construction variables from the Environment into the specified string, returning the expanded result. Construction variables are specified by a $ prefix in the string and begin with an initial underscore or alphabetic character followed by any number of underscores or alphanumeric characters. The construction variable names may be surrounded by curly braces to separate the name from trailing characters.

validate_CacheDir_class(custom_class=None)

Validate the passed custom CacheDir class, or if no args are passed, validate the custom CacheDir class from the environment.

values()

Emulates the values() method of dictionaries.

class SCons.Environment.SubstitutionEnvironment(**kw)

Bases: object

Base class for different flavors of construction environments.

This class contains a minimal set of methods that handle construction variable expansion and conversion of strings to Nodes, which may or may not be actually useful as a stand-alone class. Which methods ended up in this class is pretty arbitrary right now. They’re basically the ones which we’ve empirically determined are common to the different construction environment subclasses, and most of the others that use or touch the underlying dictionary of construction variables.

Eventually, this class should contain all the methods that we determine are necessary for a “minimal” interface to the build engine. A full “native Python” SCons environment has gotten pretty heavyweight with all of the methods and Tools and construction variables we’ve jammed in there, so it would be nice to have a lighter weight alternative for interfaces that don’t need all of the bells and whistles. (At some point, we’ll also probably rename this class “Base,” since that more reflects what we want this class to become, but because we’ve released comments that tell people to subclass Environment.Base to create their own flavors of construction environment, we’ll save that for a future refactoring when this class actually becomes useful.)

AddMethod(function, name=None)

Adds the specified function as a method of this construction environment with the specified name. If the name is omitted, the default name is the name of the function itself.

MergeFlags(args, unique=True) → None

Merge flags into construction variables.

Merges the flags from args into this construction environent. If args is not a dict, it is first converted to one with flags distributed into appropriate construction variables. See ParseFlags().

Parameters

• args – flags to merge

• unique – merge flags rather than appending (default: True). When merging, path variables are retained from the front, other construction variables from the end.

Override(overrides)

Produce a modified environment whose variables are overridden by the overrides dictionaries. “overrides” is a dictionary that will override the variables of this environment.

This function is much more efficient than Clone() or creating a new Environment because it doesn’t copy the construction environment dictionary, it just wraps the underlying construction environment, and doesn’t even create a wrapper object if there are no overrides.

ParseFlags(*flags) → dict

Return a dict of parsed flags.

Parse flags and return a dict with the flags distributed into the appropriate construction variable names. The flags are treated as a typical set of command-line flags for a GNU-style toolchain, such as might have been generated by one of the {foo}-config scripts, and used to populate the entries based on knowledge embedded in this method - the choices are not expected to be portable to other toolchains.

If one of the flags strings begins with a bang (exclamation mark), it is assumed to be a command and the rest of the string is executed; the result of that evaluation is then added to the dict.

RemoveMethod(function)

Removes the specified function’s MethodWrapper from the added_methods list, so we don’t re-bind it when making a clone.

_init_special()

Initial the dispatch tables for special handling of special construction variables.

arg2nodes(args, node_factory=<class 'SCons.Environment._Null'>, lookup_list=<class 'SCons.Environment._Null'>, **kw)

backtick(command) → str

Emulate command substitution.

Provides behavior conceptually like POSIX Shell notation for running a command in backquotes (backticks) by running command and returning the resulting output string.

This is not really a public API any longer, it is provided for the use of ParseFlags() (which supports it using a syntax of !command) and ParseConfig().

Raises

OSError – if the external command returned non-zero exit status.

get(key, default=None)

Emulates the get() method of dictionaries.

gvars()

items()

Emulates the items() method of dictionaries.

keys()

Emulates the keys() method of dictionaries.

lvars()

setdefault(key, default=None)

Emulates the setdefault() method of dictionaries.

subst(string, raw=0, target=None, source=None, conv=None, executor=None)

Recursively interpolates construction variables from the Environment into the specified string, returning the expanded result. Construction variables are specified by a $ prefix in the string and begin with an initial underscore or alphabetic character followed by any number of underscores or alphanumeric characters. The construction variable names may be surrounded by curly braces to separate the name from trailing characters.

subst_kw(kw, raw=0, target=None, source=None)

subst_list(string, raw=0, target=None, source=None, conv=None, executor=None)

Calls through to SCons.Subst.scons_subst_list(). See the documentation for that function.

subst_path(path, target=None, source=None)

Substitute a path list, turning EntryProxies into Nodes and leaving Nodes (and other objects) as-is.

subst_target_source(string, raw=0, target=None, source=None, conv=None, executor=None)

Recursively interpolates construction variables from the Environment into the specified string, returning the expanded result. Construction variables are specified by a $ prefix in the string and begin with an initial underscore or alphabetic character followed by any number of underscores or alphanumeric characters. The construction variable names may be surrounded by curly braces to separate the name from trailing characters.

values()

Emulates the values() method of dictionaries.

class SCons.Environment._Null

Bases: object

SCons.Environment._del_SCANNERS(env, key)

SCons.Environment._delete_duplicates(l, keep_last)

Delete duplicates from a sequence, keeping the first or last.

SCons.Environment._null

alias of SCons.Environment._Null

SCons.Environment._set_BUILDERS(env, key, value)

SCons.Environment._set_SCANNERS(env, key, value)

SCons.Environment._set_future_reserved(env, key, value)

SCons.Environment._set_reserved(env, key, value)

SCons.Environment.alias_builder(env, target, source)

SCons.Environment.apply_tools(env, tools, toolpath)

SCons.Environment.copy_non_reserved_keywords(dict)

SCons.Environment.default_copy_from_cache(env, src, dst)

SCons.Environment.default_copy_to_cache(env, src, dst)

SCons.Environment.default_decide_source(dependency, target, prev_ni, repo_node=None)

SCons.Environment.default_decide_target(dependency, target, prev_ni, repo_node=None)

SCons.Environment.is_valid_construction_var(varstr)

Return if the specified string is a legitimate construction variable.

SCons.Errors module

SCons exception classes.

Used to handle internal and user errors in SCons.

exception SCons.Errors.BuildError(node=None, errstr='Unknown error', status=2, exitstatus=2, filename=None, executor=None, action=None, command=None, exc_info=(None, None, None))

Bases: Exception

SCons Errors that can occur while building.

A BuildError exception contains information both about the erorr itself, and what caused the error.

Variables

• node – (cause) the error occurred while building this target node(s)

• errstr – (info) a description of the error message

• status – (info) the return code of the action that caused the build error. Must be set to a non-zero value even if the build error is not due to an action returning a non-zero returned code.

• exitstatus – (info) SCons exit status due to this build error. Must be nonzero unless due to an explicit Exit() call. Not always the same as status, since actions return a status code that should be respected, but SCons typically exits with 2 irrespective of the return value of the failed action.

• filename – (info) The name of the file or directory that caused the build error. Set to None if no files are associated with this error. This might be different from the target being built. For example, failure to create the directory in which the target file will appear. It can be None if the error is not due to a particular filename.

• executor – (cause) the executor that caused the build to fail (might be None if the build failures is not due to the executor failing)

• action – (cause) the action that caused the build to fail (might be None if the build failures is not due to the an action failure)

• command – (cause) the command line for the action that caused the build to fail (might be None if the build failures is not due to the an action failure)

• exc_info – (info) Info about exception that caused the build error. Set to (None, None, None) if this build error is not due to an exception.

exception SCons.Errors.ExplicitExit(node=None, status=None, *args)

Bases: Exception

exception SCons.Errors.InternalError

Bases: Exception

exception SCons.Errors.MSVCError

Bases: OSError

exception SCons.Errors.SConsEnvironmentError

Bases: Exception

exception SCons.Errors.StopError

Bases: Exception

exception SCons.Errors.UserError

Bases: Exception

SCons.Errors.convert_to_BuildError(status, exc_info=None)

Convert a return code to a BuildError Exception.

The buildError.status we set here will normally be used as the exit status of the “scons” process.

Parameters

• status – can either be a return code or an Exception.

• exc_info (tuple, optional) – explicit exception information.

SCons.Executor module

Execute actions with specific lists of target and source Nodes.

SCons.Executor.AddBatchExecutor(key, executor)

class SCons.Executor.Batch(targets=[], sources=[])

Bases: object

Remembers exact association between targets and sources of executor.

sources

targets

class SCons.Executor.Executor(action, env=None, overridelist=[{}], targets=[], sources=[], builder_kw={})

Bases: object

A class for controlling instances of executing an action.

This largely exists to hold a single association of an action, environment, list of environment override dictionaries, targets and sources for later processing as needed.

_changed_sources_list

_changed_targets_list

_do_execute

_execute_str

_get_changed_sources(*args, **kw)

_get_changed_targets(*args, **kw)

_get_changes()

_get_source(*args, **kw)

_get_sources(*args, **kw)

_get_target(*args, **kw)

_get_targets(*args, **kw)

_get_unchanged_sources(*args, **kw)

_get_unchanged_targets(*args, **kw)

_get_unignored_sources_key(node, ignore=())

_memo

_unchanged_sources_list

_unchanged_targets_list

action_list

add_batch(targets, sources)

Add pair of associated target and source to this Executor’s list. This is necessary for “batch” Builders that can be called repeatedly to build up a list of matching target and source files that will be used in order to update multiple target files at once from multiple corresponding source files, for tools like MSVC that support it.

add_post_action(action)

add_pre_action(action)

add_sources(sources)

Add source files to this Executor’s list. This is necessary for “multi” Builders that can be called repeatedly to build up a source file list for a given target.

batches

builder_kw

cleanup()

env

get_action_list()

get_action_side_effects()

Returns all side effects for all batches of this Executor used by the underlying Action.

get_action_targets()

get_all_children()

Returns all unique children (dependencies) for all batches of this Executor.

The Taskmaster can recognize when it’s already evaluated a Node, so we don’t have to make this list unique for its intended canonical use case, but we expect there to be a lot of redundancy (long lists of batched .cc files #including the same .h files over and over), so removing the duplicates once up front should save the Taskmaster a lot of work.

get_all_prerequisites()

Returns all unique (order-only) prerequisites for all batches of this Executor.

get_all_sources()

Returns all sources for all batches of this Executor.

get_all_targets()

Returns all targets for all batches of this Executor.

get_build_env()

Fetch or create the appropriate build Environment for this Executor.

get_build_scanner_path(scanner)

Fetch the scanner path for this executor’s targets and sources.

get_contents()

Fetch the signature contents. This is the main reason this class exists, so we can compute this once and cache it regardless of how many target or source Nodes there are.

Returns bytes

get_implicit_deps()

Return the executor’s implicit dependencies, i.e. the nodes of the commands to be executed.

get_kw(kw={})

get_lvars()

get_sources()

get_timestamp()

Fetch a time stamp for this Executor. We don’t have one, of course (only files do), but this is the interface used by the timestamp module.

get_unignored_sources(node, ignore=())

lvars

nullify()

overridelist

post_actions

pre_actions

prepare()

Preparatory checks for whether this Executor can go ahead and (try to) build its targets.

scan(scanner, node_list)

Scan a list of this Executor’s files (targets or sources) for implicit dependencies and update all of the targets with them. This essentially short-circuits an N*M scan of the sources for each individual target, which is a hell of a lot more efficient.

scan_sources(scanner)

scan_targets(scanner)

set_action_list(action)

SCons.Executor.GetBatchExecutor(key)

class SCons.Executor.Null(*args, **kw)

Bases: object

A null Executor, with a null build Environment, that does nothing when the rest of the methods call it.

This might be able to disappear when we refactor things to disassociate Builders from Nodes entirely, so we’re not going to worry about unit tests for this–at least for now.

_changed_sources_list

_changed_targets_list

_do_execute

_execute_str

_memo

_morph()

Morph this Null executor to a real Executor object.

_unchanged_sources_list

_unchanged_targets_list

action_list

add_post_action(action)

add_pre_action(action)

batches

builder_kw

cleanup()

env

get_action_list()

get_action_side_effects()

get_action_targets()

get_all_children()

get_all_prerequisites()

get_all_sources()

get_all_targets()

get_build_env()

get_build_scanner_path()

get_contents()

get_unignored_sources(*args, **kw)

lvars

overridelist

post_actions

pre_actions

prepare()

set_action_list(action)

class SCons.Executor.NullEnvironment(*args, **kwargs)

Bases: SCons.Util.Null

SCons = <module 'SCons' from '/Users/bdbaddog/devel/scons/git/mwichmann/SCons/__init__.py'>

_CacheDir = <SCons.CacheDir.CacheDir object>

_CacheDir_path = None

get_CacheDir()

class SCons.Executor.TSList(func)

Bases: collections.UserList

A class that implements $TARGETS or $SOURCES expansions by wrapping an executor Method. This class is used in the Executor.lvars() to delay creation of NodeList objects until they’re needed.

Note that we subclass collections.UserList purely so that the is_Sequence() function will identify an object of this class as a list during variable expansion. We’re not really using any collections.UserList methods in practice.

_abc_impl = <_abc_data object>

append(item)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

copy()

count(value) → integer -- return number of occurrences of value

extend(other)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(item)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

sort(*args, **kwds)

class SCons.Executor.TSObject(func)

Bases: object

A class that implements $TARGET or $SOURCE expansions by wrapping an Executor method.

SCons.Executor.execute_action_list(obj, target, kw)

Actually execute the action list.

SCons.Executor.execute_actions_str(obj)

SCons.Executor.execute_nothing(obj, target, kw)

SCons.Executor.execute_null_str(obj)

SCons.Executor.get_NullEnvironment()

Use singleton pattern for Null Environments.

SCons.Executor.rfile(node)

A function to return the results of a Node’s rfile() method, if it exists, and the Node itself otherwise (if it’s a Value Node, e.g.).

SCons.Job module

Serial and Parallel classes to execute build tasks.

The Jobs class provides a higher level interface to start, stop, and wait on jobs.

class SCons.Job.InterruptState

Bases: object

set()

class SCons.Job.Jobs(num, taskmaster)

Bases: object

An instance of this class initializes N jobs, and provides methods for starting, stopping, and waiting on all N jobs.

_reset_sig_handler()

Restore the signal handlers to their previous state (before the call to _setup_sig_handler().

_setup_sig_handler()

Setup an interrupt handler so that SCons can shutdown cleanly in various conditions:

1. SIGINT: Keyboard interrupt

2. SIGTERM: kill or system shutdown

3. SIGHUP: Controlling shell exiting

We handle all of these cases by stopping the taskmaster. It turns out that it’s very difficult to stop the build process by throwing asynchronously an exception such as KeyboardInterrupt. For example, the python Condition variables (threading.Condition) and queues do not seem to be asynchronous-exception-safe. It would require adding a whole bunch of try/finally block and except KeyboardInterrupt all over the place.

Note also that we have to be careful to handle the case when SCons forks before executing another process. In that case, we want the child to exit immediately.

run(postfunc=<function Jobs.<lambda>>)

Run the jobs.

postfunc() will be invoked after the jobs has run. It will be invoked even if the jobs are interrupted by a keyboard interrupt (well, in fact by a signal such as either SIGINT, SIGTERM or SIGHUP). The execution of postfunc() is protected against keyboard interrupts and is guaranteed to run to completion.

were_interrupted()

Returns whether the jobs were interrupted by a signal.

class SCons.Job.Parallel(taskmaster, num, stack_size)

Bases: object

This class is used to execute tasks in parallel, and is somewhat less efficient than Serial, but is appropriate for parallel builds.

This class is thread safe.

start()

Start the job. This will begin pulling tasks from the taskmaster and executing them, and return when there are no more tasks. If a task fails to execute (i.e. execute() raises an exception), then the job will stop.

class SCons.Job.Serial(taskmaster)

Bases: object

This class is used to execute tasks in series, and is more efficient than Parallel, but is only appropriate for non-parallel builds. Only one instance of this class should be in existence at a time.

This class is not thread safe.

start()

Start the job. This will begin pulling tasks from the taskmaster and executing them, and return when there are no more tasks. If a task fails to execute (i.e. execute() raises an exception), then the job will stop.

class SCons.Job.ThreadPool(num, stack_size, interrupted)

Bases: object

This class is responsible for spawning and managing worker threads.

cleanup()

Shuts down the thread pool, giving each worker thread a chance to shut down gracefully.

get()

Remove and return a result tuple from the results queue.

preparation_failed(task)

put(task)

Put task into request queue.

class SCons.Job.Worker(requestQueue, resultsQueue, interrupted)

Bases: threading.Thread

A worker thread waits on a task to be posted to its request queue, dequeues the task, executes it, and posts a tuple including the task and a boolean indicating whether the task executed successfully.

_bootstrap()

_bootstrap_inner()

_delete()

Remove current thread from the dict of currently running threads.

_exc_info()

exc_info() -> (type, value, traceback)

Return information about the most recent exception caught by an except clause in the current stack frame or in an older stack frame.

_initialized = False

_reset_internal_locks(is_alive)

_set_ident()

_set_tstate_lock()

Set a lock object which will be released by the interpreter when the underlying thread state (see pystate.h) gets deleted.

_stop()

_wait_for_tstate_lock(block=True, timeout=- 1)

property daemon

A boolean value indicating whether this thread is a daemon thread.

This must be set before start() is called, otherwise RuntimeError is raised. Its initial value is inherited from the creating thread; the main thread is not a daemon thread and therefore all threads created in the main thread default to daemon = False.

The entire Python program exits when only daemon threads are left.

getName()

property ident

Thread identifier of this thread or None if it has not been started.

This is a nonzero integer. See the get_ident() function. Thread identifiers may be recycled when a thread exits and another thread is created. The identifier is available even after the thread has exited.

isAlive()

Return whether the thread is alive.

This method is deprecated, use is_alive() instead.

isDaemon()

is_alive()

Return whether the thread is alive.

This method returns True just before the run() method starts until just after the run() method terminates. The module function enumerate() returns a list of all alive threads.

join(timeout=None)

Wait until the thread terminates.

This blocks the calling thread until the thread whose join() method is called terminates – either normally or through an unhandled exception or until the optional timeout occurs.

When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof). As join() always returns None, you must call is_alive() after join() to decide whether a timeout happened – if the thread is still alive, the join() call timed out.

When the timeout argument is not present or None, the operation will block until the thread terminates.

A thread can be join()ed many times.

join() raises a RuntimeError if an attempt is made to join the current thread as that would cause a deadlock. It is also an error to join() a thread before it has been started and attempts to do so raises the same exception.

property name

A string used for identification purposes only.

It has no semantics. Multiple threads may be given the same name. The initial name is set by the constructor.

run()

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

setDaemon(daemonic)

setName(name)

start()

Start the thread’s activity.

It must be called at most once per thread object. It arranges for the object’s run() method to be invoked in a separate thread of control.

This method will raise a RuntimeError if called more than once on the same thread object.

SCons.Memoize module

Decorator-based memoizer to count caching stats.

A decorator-based implementation to count hits and misses of the computed values that various methods cache in memory.

Use of this modules assumes that wrapped methods be coded to cache their values in a consistent way. In particular, it requires that the class uses a dictionary named “_memo” to store the cached values.

Here is an example of wrapping a method that returns a computed value, with no input parameters:

@SCons.Memoize.CountMethodCall
def foo(self):

    try:                                                    # Memoization
        return self._memo['foo']                            # Memoization
    except KeyError:                                        # Memoization
        pass                                                # Memoization

    result = self.compute_foo_value()

    self._memo['foo'] = result                              # Memoization

    return result

Here is an example of wrapping a method that will return different values based on one or more input arguments:

def _bar_key(self, argument):                               # Memoization
    return argument                                         # Memoization

@SCons.Memoize.CountDictCall(_bar_key)
def bar(self, argument):

    memo_key = argument                                     # Memoization
    try:                                                    # Memoization
        memo_dict = self._memo['bar']                       # Memoization
    except KeyError:                                        # Memoization
        memo_dict = {}                                      # Memoization
        self._memo['dict'] = memo_dict                      # Memoization
    else:                                                   # Memoization
        try:                                                # Memoization
            return memo_dict[memo_key]                      # Memoization
        except KeyError:                                    # Memoization
            pass                                            # Memoization

    result = self.compute_bar_value(argument)

    memo_dict[memo_key] = result                            # Memoization

    return result

Deciding what to cache is tricky, because different configurations can have radically different performance tradeoffs, and because the tradeoffs involved are often so non-obvious. Consequently, deciding whether or not to cache a given method will likely be more of an art than a science, but should still be based on available data from this module. Here are some VERY GENERAL guidelines about deciding whether or not to cache return values from a method that’s being called a lot:

– The first question to ask is, “Can we change the calling code

so this method isn’t called so often?” Sometimes this can be done by changing the algorithm. Sometimes the caller should be memoized, not the method you’re looking at.

—The memoized function should be timed with multiple configurations to make sure it doesn’t inadvertently slow down some other configuration.

– When memoizing values based on a dictionary key composed of

input arguments, you don’t need to use all of the arguments if some of them don’t affect the return values.

class SCons.Memoize.CountDict(cls_name, method_name, keymaker)

Bases: SCons.Memoize.Counter

A counter class for memoized values stored in a dictionary, with keys based on the method’s input arguments.

A CountDict object is instantiated in a decorator for each of the class’s methods that memoizes its return value in a dictionary, indexed by some key that can be computed from one or more of its input arguments.

count(*args, **kw)

Counts whether the computed key value is already present in the memoization dictionary (a hit) or not (a miss).

display()

key()

SCons.Memoize.CountDictCall(keyfunc)

Decorator for counting memoizer hits/misses while accessing dictionary values with a key-generating function. Like CountMethodCall above, it wraps the given method fn and uses a CountDict object to keep track of the caching statistics. The dict-key function keyfunc has to get passed in the decorator call and gets stored in the CountDict instance. Wrapping gets enabled by calling EnableMemoization().

SCons.Memoize.CountMethodCall(fn)

Decorator for counting memoizer hits/misses while retrieving a simple value in a class method. It wraps the given method fn and uses a CountValue object to keep track of the caching statistics. Wrapping gets enabled by calling EnableMemoization().

class SCons.Memoize.CountValue(cls_name, method_name)

Bases: SCons.Memoize.Counter

A counter class for simple, atomic memoized values.

A CountValue object should be instantiated in a decorator for each of the class’s methods that memoizes its return value by simply storing the return value in its _memo dictionary.

count(*args, **kw)

Counts whether the memoized value has already been set (a hit) or not (a miss).

display()

key()

class SCons.Memoize.Counter(cls_name, method_name)

Bases: object

Base class for counting memoization hits and misses.

We expect that the initialization in a matching decorator will fill in the correct class name and method name that represents the name of the function being counted.

display()

key()

SCons.Memoize.Dump(title=None)

Dump the hit/miss count for all the counters collected so far.

SCons.Memoize.EnableMemoization()

SCons.PathList module

Handle lists of directory paths.

These are the path lists that get set as CPPPATH, LIBPATH, etc.) with as much caching of data and efficiency as we can, while still keeping the evaluation delayed so that we Do the Right Thing (almost) regardless of how the variable is specified.

SCons.PathList.PathList(pathlist)

Returns the cached _PathList object for the specified pathlist, creating and caching a new object as necessary.

class SCons.PathList._PathList(pathlist)

Bases: object

An actual PathList object.

subst_path(env, target, source)

Performs construction variable substitution on a pre-digested PathList for a specific target and source.

SCons.PathList.node_conv(obj)

This is the “string conversion” routine that we have our substitutions use to return Nodes, not strings. This relies on the fact that an EntryProxy object has a get() method that returns the underlying Node that it wraps, which is a bit of architectural dependence that we might need to break or modify in the future in response to additional requirements.

SCons.SConf module

Autoconf-like configuration support.

In other words, SConf allows to run tests on the build machine to detect capabilities of system and do some things based on result: generate config files, header files for C/C++, update variables in environment.

Tests on the build system can detect if compiler sees header files, if libraries are installed, if some command line options are supported etc.

SCons.SConf.CheckCC(context)

SCons.SConf.CheckCHeader(context, header, include_quotes='""')

A test for a C header file.

SCons.SConf.CheckCXX(context)

SCons.SConf.CheckCXXHeader(context, header, include_quotes='""')

A test for a C++ header file.

class SCons.SConf.CheckContext(sconf)

Bases: object

Provides a context for configure tests. Defines how a test writes to the screen and log file.

A typical test is just a callable with an instance of CheckContext as first argument:

def CheckCustom(context, …):

context.Message(‘Checking my weird test … ‘) ret = myWeirdTestFunction(…) context.Result(ret)

Often, myWeirdTestFunction will be one of context.TryCompile/context.TryLink/context.TryRun. The results of those are cached, for they are only rebuild, if the dependencies have changed.

AppendLIBS(lib_name_list)

BuildProg(text, ext)

CompileProg(text, ext)

CompileSharedObject(text, ext)

Display(msg)

Log(msg)

Message(text)

Inform about what we are doing right now, e.g. ‘Checking for SOMETHING … ‘

PrependLIBS(lib_name_list)

Result(res)

Inform about the result of the test. If res is not a string, displays ‘yes’ or ‘no’ depending on whether res is evaluated as true or false. The result is only displayed when self.did_show_result is not set.

RunProg(text, ext)

SetLIBS(val)

TryAction(*args, **kw)

TryBuild(*args, **kw)

TryCompile(*args, **kw)

TryLink(*args, **kw)

TryRun(*args, **kw)

SCons.SConf.CheckDeclaration(context, declaration, includes='', language=None)

SCons.SConf.CheckFunc(context, function_name, header=None, language=None)

SCons.SConf.CheckHeader(context, header, include_quotes='<>', language=None)

A test for a C or C++ header file.

SCons.SConf.CheckLib(context, library=None, symbol='main', header=None, language=None, autoadd=1)

A test for a library. See also CheckLibWithHeader. Note that library may also be None to test whether the given symbol compiles without flags.

SCons.SConf.CheckLibWithHeader(context, libs, header, language, call=None, autoadd=1)

Another (more sophisticated) test for a library. Checks, if library and header is available for language (may be ‘C’ or ‘CXX’). Call maybe be a valid expression _with_ a trailing ‘;’. As in CheckLib, we support library=None, to test if the call compiles without extra link flags.

SCons.SConf.CheckMember(context, aggregate_member, header=None, language=None)

Returns the status (False : failed, True : ok).

SCons.SConf.CheckProg(context, prog_name)

Simple check if a program exists in the path. Returns the path for the application, or None if not found.

SCons.SConf.CheckSHCC(context)

SCons.SConf.CheckSHCXX(context)

SCons.SConf.CheckType(context, type_name, includes='', language=None)

SCons.SConf.CheckTypeSize(context, type_name, includes='', language=None, expect=None)

exception SCons.SConf.ConfigureCacheError(target)

Bases: SCons.SConf.SConfError

Raised when a use explicitely requested the cache feature, but the test is run the first time.

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.SConf.ConfigureDryRunError(target)

Bases: SCons.SConf.SConfError

Raised when a file or directory needs to be updated during a Configure process, but the user requested a dry-run

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

SCons.SConf.CreateConfigHBuilder(env)

Called if necessary just before the building targets phase begins.

SCons.SConf.NeedConfigHBuilder()

SCons.SConf.SConf(*args, **kw)

class SCons.SConf.SConfBase(env, custom_tests={}, conf_dir='$CONFIGUREDIR', log_file='$CONFIGURELOG', config_h=None, _depth=0)

Bases: object

This is simply a class to represent a configure context. After creating a SConf object, you can call any tests. After finished with your tests, be sure to call the Finish() method, which returns the modified environment. Some words about caching: In most cases, it is not necessary to cache Test results explicitly. Instead, we use the scons dependency checking mechanism. For example, if one wants to compile a test program (SConf.TryLink), the compiler is only called, if the program dependencies have changed. However, if the program could not be compiled in a former SConf run, we need to explicitly cache this error.

AddTest(test_name, test_instance)

Adds test_class to this SConf instance. It can be called with self.test_name(…)

AddTests(tests)

Adds all the tests given in the tests dictionary to this SConf instance

BuildNodes(nodes)

Tries to build the given nodes immediately. Returns 1 on success, 0 on error.

Define(name, value=None, comment=None)

Define a pre processor symbol name, with the optional given value in the current config header.

If value is None (default), then #define name is written. If value is not none, then #define name value is written.

comment is a string which will be put as a C comment in the header, to explain the meaning of the value (appropriate C comments will be added automatically).

Finish()

Call this method after finished with your tests: env = sconf.Finish()

class TestWrapper(test, sconf)

Bases: object

A wrapper around Tests (to ensure sanity)

TryAction(action, text=None, extension='')

Tries to execute the given action with optional source file contents <text> and optional source file extension <extension>, Returns the status (0 : failed, 1 : ok) and the contents of the output file.

TryBuild(builder, text=None, extension='')

Low level TryBuild implementation. Normally you don’t need to call that - you can use TryCompile / TryLink / TryRun instead

TryCompile(text, extension)

Compiles the program given in text to an env.Object, using extension as file extension (e.g. ‘.c’). Returns 1, if compilation was successful, 0 otherwise. The target is saved in self.lastTarget (for further processing).

TryLink(text, extension)

Compiles the program given in text to an executable env.Program, using extension as file extension (e.g. ‘.c’). Returns 1, if compilation was successful, 0 otherwise. The target is saved in self.lastTarget (for further processing).

TryRun(text, extension)

Compiles and runs the program given in text, using extension as file extension (e.g. ‘.c’). Returns (1, outputStr) on success, (0, ‘’) otherwise. The target (a file containing the program’s stdout) is saved in self.lastTarget (for further processing).

_createDir(node)

_shutdown()

Private method. Reset to non-piped spawn

_startup()

Private method. Set up logstream, and set the environment variables necessary for a piped build

pspawn_wrapper(sh, escape, cmd, args, env)

Wrapper function for handling piped spawns.

This looks to the calling interface (in Action.py) like a “normal” spawn, but associates the call with the PSPAWN variable from the construction environment and with the streams to which we want the output logged. This gets slid into the construction environment as the SPAWN variable so Action.py doesn’t have to know or care whether it’s spawning a piped command or not.

class SCons.SConf.SConfBuildInfo

Bases: SCons.Node.FS.FileBuildInfo

Special build info for targets of configure tests. Additional members are result (did the builder succeed last time?) and string, which contains messages of the original build phase.

__getstate__()

Return all fields that shall be pickled. Walk the slots in the class hierarchy and add those to the state dictionary. If a ‘__dict__’ slot is available, copy all entries to the dictionary. Also include the version id, which is fixed for all instances of a class.

__setstate__(state)

Restore the attributes from a pickled state.

bact

bactsig

bdepends

bdependsigs

bimplicit

bimplicitsigs

bsources

bsourcesigs

convert_from_sconsign(dir, name)

Converts a newly-read FileBuildInfo object for in-SCons use

For normal up-to-date checking, we don’t have any conversion to perform–but we’re leaving this method here to make that clear.

convert_to_sconsign()

Converts this FileBuildInfo object for writing to a .sconsign file

This replaces each Node in our various dependency lists with its usual string representation: relative to the top-level SConstruct directory, or an absolute path if it’s outside.

current_version_id = 2

dependency_map

format(names=0)

merge(other)

Merge the fields of another object into this object. Already existing information is overwritten by the other instance’s data. WARNING: If a ‘__dict__’ slot is added, it should be updated instead of replaced.

prepare_dependencies()

Prepares a FileBuildInfo object for explaining what changed

The bsources, bdepends and bimplicit lists have all been stored on disk as paths relative to the top-level SConstruct directory. Convert the strings to actual Nodes (for use by the –debug=explain code and –implicit-cache).

result

set_build_result(result, string)

string

class SCons.SConf.SConfBuildTask(tm, targets, top, node)

Bases: SCons.Taskmaster.AlwaysTask

This is almost the same as SCons.Script.BuildTask. Handles SConfErrors correctly and knows about the current cache_mode.

_abc_impl = <_abc_data object>

_exception_raise()

Raises a pending exception that was recorded while getting a Task ready for execution.

_no_exception_to_raise()

collect_node_states()

display(message)

Hook to allow the calling interface to display a message.

This hook gets called as part of preparing a task for execution (that is, a Node to be built). As part of figuring out what Node should be built next, the actual target list may be altered, along with a message describing the alteration. The calling interface can subclass Task and provide a concrete implementation of this method to see those messages.

display_cached_string(bi)

Logs the original builder messages, given the SConfBuildInfo instance bi.

exc_clear()

Clears any recorded exception.

This also changes the “exception_raise” attribute to point to the appropriate do-nothing method.

exc_info()

Returns info about a recorded exception.

exception_set(exception=None)

Records an exception to be raised at the appropriate time.

This also changes the “exception_raise” attribute to point to the method that will, in fact

execute()

Called to execute the task.

This method is called from multiple threads in a parallel build, so only do thread safe stuff here. Do thread unsafe stuff in prepare(), executed() or failed().

executed()

Called when the task has been successfully executed and the Taskmaster instance wants to call the Node’s callback methods.

This may have been a do-nothing operation (to preserve build order), so we must check the node’s state before deciding whether it was “built”, in which case we call the appropriate Node method. In any event, we always call “visited()”, which will handle any post-visit actions that must take place regardless of whether or not the target was an actual built target or a source Node.

executed_with_callbacks()

Called when the task has been successfully executed and the Taskmaster instance wants to call the Node’s callback methods.

This may have been a do-nothing operation (to preserve build order), so we must check the node’s state before deciding whether it was “built”, in which case we call the appropriate Node method. In any event, we always call “visited()”, which will handle any post-visit actions that must take place regardless of whether or not the target was an actual built target or a source Node.

executed_without_callbacks()

Called when the task has been successfully executed and the Taskmaster instance doesn’t want to call the Node’s callback methods.

fail_continue()

Explicit continue-the-build failure.

This sets failure status on the target nodes and all of their dependent parent nodes.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

fail_stop()

Explicit stop-the-build failure.

This sets failure status on the target nodes and all of their dependent parent nodes.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

failed()

Default action when a task fails: stop the build.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

get_target()

Fetch the target being built or updated by this task.

make_ready()

Marks all targets in a task ready for execution if any target is not current.

This is the default behavior for building only what’s necessary.

make_ready_all()

Marks all targets in a task ready for execution.

This is used when the interface needs every target Node to be visited–the canonical example being the “scons -c” option.

make_ready_current()

Marks all targets in a task ready for execution if any target is not current.

This is the default behavior for building only what’s necessary.

needs_execute()

Always returns True (indicating this Task should always be executed).

Subclasses that need this behavior (as opposed to the default of only executing Nodes that are out of date w.r.t. their dependencies) can use this as follows:

class MyTaskSubclass(SCons.Taskmaster.Task):

needs_execute = SCons.Taskmaster.AlwaysTask.needs_execute

postprocess()

Post-processes a task after it’s been executed.

This examines all the targets just built (or not, we don’t care if the build was successful, or even if there was no build because everything was up-to-date) to see if they have any waiting parent Nodes, or Nodes waiting on a common side effect, that can be put back on the candidates list.

prepare()

Called just before the task is executed.

This is mainly intended to give the target Nodes a chance to unlink underlying files and make all necessary directories before the Action is actually called to build the targets.

trace_message(method, node, description='node')

exception SCons.SConf.SConfError(msg)

Bases: SCons.Errors.UserError

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.SConf.SConfWarning

Bases: SCons.Warnings.SConsWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

SCons.SConf.SetBuildType(buildtype)

SCons.SConf.SetCacheMode(mode)

Set the Configure cache mode. mode must be one of “auto”, “force”, or “cache”.

SCons.SConf.SetProgressDisplay(display)

Set the progress display to use (called from SCons.Script)

class SCons.SConf.Streamer(orig)

Bases: object

‘Sniffer’ for a file-like writable object. Similar to the unix tool tee.

flush()

getvalue()

Return everything written to orig since the Streamer was created.

write(str)

writelines(lines)

SCons.SConf._createConfigH(target, source, env)

SCons.SConf._createSource(target, source, env)

SCons.SConf._set_conftest_node(node)

SCons.SConf._stringConfigH(target, source, env)

SCons.SConf._stringSource(target, source, env)

SCons.SConf.createIncludesFromHeaders(headers, leaveLast, include_quotes='""')

SCons.SConsign module

Operations on signature database files (.sconsign).

class SCons.SConsign.Base

Bases: object

This is the controlling class for the signatures for the collection of entries associated with a specific directory. The actual directory association will be maintained by a subclass that is specific to the underlying storage method. This class provides a common set of methods for fetching and storing the individual bits of information that make up signature entry.

do_not_set_entry(filename, obj)

do_not_store_info(filename, node)

get_entry(filename)

Fetch the specified entry attribute.

merge()

set_entry(filename, obj)

Set the entry.

store_info(filename, node)

class SCons.SConsign.DB(dir)

Bases: SCons.SConsign.Base

A Base subclass that reads and writes signature information from a global .sconsign.db* file–the actual file suffix is determined by the database module.

do_not_set_entry(filename, obj)

do_not_store_info(filename, node)

get_entry(filename)

Fetch the specified entry attribute.

merge()

set_entry(filename, obj)

Set the entry.

store_info(filename, node)

write(sync=1)

class SCons.SConsign.Dir(fp=None, dir=None)

Bases: SCons.SConsign.Base

do_not_set_entry(filename, obj)

do_not_store_info(filename, node)

get_entry(filename)

Fetch the specified entry attribute.

merge()

set_entry(filename, obj)

Set the entry.

store_info(filename, node)

class SCons.SConsign.DirFile(dir)

Bases: SCons.SConsign.Dir

Encapsulates reading and writing a per-directory .sconsign file.

do_not_set_entry(filename, obj)

do_not_store_info(filename, node)

get_entry(filename)

Fetch the specified entry attribute.

merge()

set_entry(filename, obj)

Set the entry.

store_info(filename, node)

write(sync=1)

Write the .sconsign file to disk.

Try to write to a temporary file first, and rename it if we succeed. If we can’t write to the temporary file, it’s probably because the directory isn’t writable (and if so, how did we build anything in this directory, anyway?), so try to write directly to the .sconsign file as a backup. If we can’t rename, try to copy the temporary contents back to the .sconsign file. Either way, always try to remove the temporary file at the end.

SCons.SConsign.File(name, dbm_module=None)

Arrange for all signatures to be stored in a global .sconsign.db* file.

SCons.SConsign.ForDirectory

alias of SCons.SConsign.DB

SCons.SConsign.Get_DataBase(dir)

SCons.SConsign.Reset()

Reset global state. Used by unit tests that end up using SConsign multiple times to get a clean slate for each test.

class SCons.SConsign.SConsignEntry

Bases: object

Wrapper class for the generic entry in a .sconsign file. The Node subclass populates it with attributes as it pleases.

XXX As coded below, we do expect a ‘.binfo’ attribute to be added, but we’ll probably generalize this in the next refactorings.

binfo

convert_from_sconsign(dir, name)

convert_to_sconsign()

current_version_id = 2

ninfo

SCons.SConsign.corrupt_dblite_warning(filename)

SCons.SConsign.current_sconsign_filename()

SCons.SConsign.write()

SCons.Subst module

SCons string substitution.

class SCons.Subst.CmdStringHolder(cmd, literal=None)

Bases: collections.UserString

This is a special class used to hold strings generated by scons_subst() and scons_subst_list(). It defines a special method escape(). When passed a function with an escape algorithm for a particular platform, it will return the contained string with the proper escape sequences inserted.

_abc_impl = <_abc_data object>

capitalize()

casefold()

center(width, *args)

count(value) → integer -- return number of occurrences of value

encode(encoding=None, errors=None)

endswith(suffix, start=0, end=9223372036854775807)

escape(escape_func, quote_func=<function quote_spaces>)

Escape the string with the supplied function. The function is expected to take an arbitrary string, then return it with all special characters escaped and ready for passing to the command interpreter.

After calling this function, the next call to str() will return the escaped string.

expandtabs(tabsize=8)

find(sub, start=0, end=9223372036854775807)

format(*args, **kwds)

format_map(mapping)

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

is_literal()

isalnum()

isalpha()

isascii()

isdecimal()

isdigit()

isidentifier()

islower()

isnumeric()

isprintable()

isspace()

istitle()

isupper()

join(seq)

ljust(width, *args)

lower()

lstrip(chars=None)

maketrans(y=None, z=None, /)

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

partition(sep)

replace(old, new, maxsplit=- 1)

rfind(sub, start=0, end=9223372036854775807)

rindex(sub, start=0, end=9223372036854775807)

rjust(width, *args)

rpartition(sep)

rsplit(sep=None, maxsplit=- 1)

rstrip(chars=None)

split(sep=None, maxsplit=- 1)

splitlines(keepends=False)

startswith(prefix, start=0, end=9223372036854775807)

strip(chars=None)

swapcase()

title()

translate(*args)

upper()

zfill(width)

class SCons.Subst.ListSubber(env, mode, conv, gvars)

Bases: collections.UserList

A class to construct the results of a scons_subst_list() call.

Like StringSubber, this class binds a specific construction environment, mode, target and source with two methods (substitute() and expand()) that handle the expansion.

In addition, however, this class is used to track the state of the result(s) we’re gathering so we can do the appropriate thing whenever we have to append another word to the result–start a new line, start a new word, append to the current word, etc. We do this by setting the “append” attribute to the right method so that our wrapper methods only need ever call ListSubber.append(), and the rest of the object takes care of doing the right thing internally.

_abc_impl = <_abc_data object>

add_new_word(x)

add_to_current_word(x)

Append the string x to the end of the current last word in the result. If that is not possible, then just add it as a new word. Make sure the entire concatenated string inherits the object attributes of x (in particular, the escape function) by wrapping it as CmdStringHolder.

append(item)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

close_strip(x)

Handle the “close strip” $) token.

copy()

count(value) → integer -- return number of occurrences of value

expand(s, lvars, within_list)

Expand a single “token” as necessary, appending the expansion to the current result.

This handles expanding different types of things (strings, lists, callables) appropriately. It calls the wrapper substitute() method to re-expand things as necessary, so that the results of expansions of side-by-side strings still get re-evaluated separately, not smushed together.

expanded(s)

Determines if the string s requires further expansion.

Due to the implementation of ListSubber expand will call itself 2 additional times for an already expanded string. This method is used to determine if a string is already fully expanded and if so exit the loop early to prevent these recursive calls.

extend(other)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)

S.insert(index, value) – insert value before index

literal(x)

next_line()

Arrange for the next word to start a new line. This is like starting a new word, except that we have to append another line to the result.

next_word()

Arrange for the next word to start a new word.

open_strip(x)

Handle the “open strip” $( token.

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(item)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

sort(*args, **kwds)

substitute(args, lvars, within_list)

Substitute expansions in an argument or list of arguments.

This serves as a wrapper for splitting up a string into separate tokens.

this_word()

Arrange for the next word to append to the end of the current last word in the result.

class SCons.Subst.Literal(lstr)

Bases: object

A wrapper for a string. If you use this object wrapped around a string, then it will be interpreted as literal. When passed to the command interpreter, all special characters will be escaped.

escape(escape_func)

for_signature()

is_literal()

class SCons.Subst.NLWrapper(list, func)

Bases: object

A wrapper class that delays turning a list of sources or targets into a NodeList until it’s needed. The specified function supplied when the object is initialized is responsible for turning raw nodes into proxies that implement the special attributes like .abspath, .source, etc. This way, we avoid creating those proxies just “in case” someone is going to use $TARGET or the like, and only go through the trouble if we really have to.

In practice, this might be a wash performance-wise, but it’s a little cleaner conceptually…

_create_nodelist()

_gen_nodelist()

_return_nodelist()

class SCons.Subst.NullNodeList(*args, **kwargs)

Bases: SCons.Util.NullSeq

_instance

SCons.Subst.SetAllowableExceptions(*excepts)

class SCons.Subst.SpecialAttrWrapper(lstr, for_signature=None)

Bases: object

This is a wrapper for what we call a ‘Node special attribute.’ This is any of the attributes of a Node that we can reference from Environment variable substitution, such as $TARGET.abspath or $SOURCES[1].filebase. We implement the same methods as Literal so we can handle special characters, plus a for_signature method, such that we can return some canonical string during signature calculation to avoid unnecessary rebuilds.

escape(escape_func)

for_signature()

is_literal()

class SCons.Subst.StringSubber(env, mode, conv, gvars)

Bases: object

A class to construct the results of a scons_subst() call.

This binds a specific construction environment, mode, target and source with two methods (substitute() and expand()) that handle the expansion.

expand(s, lvars)

Expand a single “token” as necessary, returning an appropriate string containing the expansion.

This handles expanding different types of things (strings, lists, callables) appropriately. It calls the wrapper substitute() method to re-expand things as necessary, so that the results of expansions of side-by-side strings still get re-evaluated separately, not smushed together.

substitute(args, lvars)

Substitute expansions in an argument or list of arguments.

This serves as a wrapper for splitting up a string into separate tokens.

class SCons.Subst.Target_or_Source(nl)

Bases: object

A class that implements $TARGET or $SOURCE expansions by in turn wrapping a NLWrapper. This class handles the different methods used to access an individual proxy Node, calling the NLWrapper to create a proxy on demand.

class SCons.Subst.Targets_or_Sources(nl)

Bases: collections.UserList

A class that implements $TARGETS or $SOURCES expansions by in turn wrapping a NLWrapper. This class handles the different methods used to access the list, calling the NLWrapper to create proxies on demand.

Note that we subclass collections.UserList purely so that the is_Sequence() function will identify an object of this class as a list during variable expansion. We’re not really using any collections.UserList methods in practice.

_abc_impl = <_abc_data object>

append(item)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

copy()

count(value) → integer -- return number of occurrences of value

extend(other)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(item)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

sort(*args, **kwds)

SCons.Subst._remove_list(list)

SCons.Subst._rm_list(list)

SCons.Subst.escape_list(mylist, escape_func)

Escape a list of arguments by running the specified escape_func on every object in the list that has an escape() method.

SCons.Subst.quote_spaces(arg)

Generic function for putting double quotes around any string that has white space in it.

SCons.Subst.raise_exception(exception, target, s)

SCons.Subst.scons_subst(strSubst, env, mode=1, target=None, source=None, gvars={}, lvars={}, conv=None)

Expand a string or list containing construction variable substitutions.

This is the work-horse function for substitutions in file names and the like. The companion scons_subst_list() function (below) handles separating command lines into lists of arguments, so see that function if that’s what you’re looking for.

SCons.Subst.scons_subst_list(strSubst, env, mode=1, target=None, source=None, gvars={}, lvars={}, conv=None)

Substitute construction variables in a string (or list or other object) and separate the arguments into a command list.

The companion scons_subst() function (above) handles basic substitutions within strings, so see that function instead if that’s what you’re looking for.

SCons.Subst.scons_subst_once(strSubst, env, key)

Perform single (non-recursive) substitution of a single construction variable keyword.

This is used when setting a variable when copying or overriding values in an Environment. We want to capture (expand) the old value before we override it, so people can do things like:

env2 = env.Clone(CCFLAGS = ‘$CCFLAGS -g’)

We do this with some straightforward, brute-force code here…

SCons.Subst.subst_dict(target, source)

Create a dictionary for substitution of special construction variables.

This translates the following special arguments:

target - the target (object or array of objects),

used to generate the TARGET and TARGETS construction variables

source - the source (object or array of objects),

used to generate the SOURCES and SOURCE construction variables

SCons.Taskmaster module

Generic Taskmaster module for the SCons build engine.

This module contains the primary interface(s) between a wrapping user interface and the SCons build engine. There are two key classes here:

Taskmaster

This is the main engine for walking the dependency graph and calling things to decide what does or doesn’t need to be built.

Task

This is the base class for allowing a wrapping interface to decide what does or doesn’t actually need to be done. The intention is for a wrapping interface to subclass this as appropriate for different types of behavior it may need.

The canonical example is the SCons native Python interface, which has Task subclasses that handle its specific behavior, like printing “‘foo’ is up to date” when a top-level target doesn’t need to be built, and handling the -c option by removing targets as its “build” action. There is also a separate subclass for suppressing this output when the -q option is used.

The Taskmaster instantiates a Task object for each (set of) target(s) that it decides need to be evaluated and/or built.

class SCons.Taskmaster.AlwaysTask(tm, targets, top, node)

Bases: SCons.Taskmaster.Task

_abc_impl = <_abc_data object>

_exception_raise()

Raises a pending exception that was recorded while getting a Task ready for execution.

_no_exception_to_raise()

display(message)

Hook to allow the calling interface to display a message.

This hook gets called as part of preparing a task for execution (that is, a Node to be built). As part of figuring out what Node should be built next, the actual target list may be altered, along with a message describing the alteration. The calling interface can subclass Task and provide a concrete implementation of this method to see those messages.

exc_clear()

Clears any recorded exception.

This also changes the “exception_raise” attribute to point to the appropriate do-nothing method.

exc_info()

Returns info about a recorded exception.

exception_set(exception=None)

Records an exception to be raised at the appropriate time.

This also changes the “exception_raise” attribute to point to the method that will, in fact

execute()

Called to execute the task.

This method is called from multiple threads in a parallel build, so only do thread safe stuff here. Do thread unsafe stuff in prepare(), executed() or failed().

executed()

Called when the task has been successfully executed and the Taskmaster instance wants to call the Node’s callback methods.

This may have been a do-nothing operation (to preserve build order), so we must check the node’s state before deciding whether it was “built”, in which case we call the appropriate Node method. In any event, we always call “visited()”, which will handle any post-visit actions that must take place regardless of whether or not the target was an actual built target or a source Node.

executed_with_callbacks()

Called when the task has been successfully executed and the Taskmaster instance wants to call the Node’s callback methods.

This may have been a do-nothing operation (to preserve build order), so we must check the node’s state before deciding whether it was “built”, in which case we call the appropriate Node method. In any event, we always call “visited()”, which will handle any post-visit actions that must take place regardless of whether or not the target was an actual built target or a source Node.

executed_without_callbacks()

Called when the task has been successfully executed and the Taskmaster instance doesn’t want to call the Node’s callback methods.

fail_continue()

Explicit continue-the-build failure.

This sets failure status on the target nodes and all of their dependent parent nodes.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

fail_stop()

Explicit stop-the-build failure.

This sets failure status on the target nodes and all of their dependent parent nodes.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

failed()

Default action when a task fails: stop the build.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

get_target()

Fetch the target being built or updated by this task.

make_ready()

Marks all targets in a task ready for execution if any target is not current.

This is the default behavior for building only what’s necessary.

make_ready_all()

Marks all targets in a task ready for execution.

This is used when the interface needs every target Node to be visited–the canonical example being the “scons -c” option.

make_ready_current()

Marks all targets in a task ready for execution if any target is not current.

This is the default behavior for building only what’s necessary.

needs_execute()

Always returns True (indicating this Task should always be executed).

Subclasses that need this behavior (as opposed to the default of only executing Nodes that are out of date w.r.t. their dependencies) can use this as follows:

class MyTaskSubclass(SCons.Taskmaster.Task):

needs_execute = SCons.Taskmaster.AlwaysTask.needs_execute

postprocess()

Post-processes a task after it’s been executed.

This examines all the targets just built (or not, we don’t care if the build was successful, or even if there was no build because everything was up-to-date) to see if they have any waiting parent Nodes, or Nodes waiting on a common side effect, that can be put back on the candidates list.

prepare()

Called just before the task is executed.

This is mainly intended to give the target Nodes a chance to unlink underlying files and make all necessary directories before the Action is actually called to build the targets.

trace_message(method, node, description='node')

class SCons.Taskmaster.OutOfDateTask(tm, targets, top, node)

Bases: SCons.Taskmaster.Task

_abc_impl = <_abc_data object>

_exception_raise()

Raises a pending exception that was recorded while getting a Task ready for execution.

_no_exception_to_raise()

display(message)

Hook to allow the calling interface to display a message.

This hook gets called as part of preparing a task for execution (that is, a Node to be built). As part of figuring out what Node should be built next, the actual target list may be altered, along with a message describing the alteration. The calling interface can subclass Task and provide a concrete implementation of this method to see those messages.

exc_clear()

Clears any recorded exception.

This also changes the “exception_raise” attribute to point to the appropriate do-nothing method.

exc_info()

Returns info about a recorded exception.

exception_set(exception=None)

Records an exception to be raised at the appropriate time.

This also changes the “exception_raise” attribute to point to the method that will, in fact

execute()

Called to execute the task.

This method is called from multiple threads in a parallel build, so only do thread safe stuff here. Do thread unsafe stuff in prepare(), executed() or failed().

executed()

Called when the task has been successfully executed and the Taskmaster instance wants to call the Node’s callback methods.

This may have been a do-nothing operation (to preserve build order), so we must check the node’s state before deciding whether it was “built”, in which case we call the appropriate Node method. In any event, we always call “visited()”, which will handle any post-visit actions that must take place regardless of whether or not the target was an actual built target or a source Node.

executed_with_callbacks()

Called when the task has been successfully executed and the Taskmaster instance wants to call the Node’s callback methods.

This may have been a do-nothing operation (to preserve build order), so we must check the node’s state before deciding whether it was “built”, in which case we call the appropriate Node method. In any event, we always call “visited()”, which will handle any post-visit actions that must take place regardless of whether or not the target was an actual built target or a source Node.

executed_without_callbacks()

Called when the task has been successfully executed and the Taskmaster instance doesn’t want to call the Node’s callback methods.

fail_continue()

Explicit continue-the-build failure.

This sets failure status on the target nodes and all of their dependent parent nodes.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

fail_stop()

Explicit stop-the-build failure.

This sets failure status on the target nodes and all of their dependent parent nodes.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

failed()

Default action when a task fails: stop the build.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

get_target()

Fetch the target being built or updated by this task.

make_ready()

Marks all targets in a task ready for execution if any target is not current.

This is the default behavior for building only what’s necessary.

make_ready_all()

Marks all targets in a task ready for execution.

This is used when the interface needs every target Node to be visited–the canonical example being the “scons -c” option.

make_ready_current()

Marks all targets in a task ready for execution if any target is not current.

This is the default behavior for building only what’s necessary.

needs_execute()

Returns True (indicating this Task should be executed) if this Task’s target state indicates it needs executing, which has already been determined by an earlier up-to-date check.

postprocess()

Post-processes a task after it’s been executed.

This examines all the targets just built (or not, we don’t care if the build was successful, or even if there was no build because everything was up-to-date) to see if they have any waiting parent Nodes, or Nodes waiting on a common side effect, that can be put back on the candidates list.

prepare()

Called just before the task is executed.

This is mainly intended to give the target Nodes a chance to unlink underlying files and make all necessary directories before the Action is actually called to build the targets.

trace_message(method, node, description='node')

class SCons.Taskmaster.Stats

Bases: object

A simple class for holding statistics about the disposition of a Node by the Taskmaster. If we’re collecting statistics, each Node processed by the Taskmaster gets one of these attached, in which case the Taskmaster records its decision each time it processes the Node. (Ideally, that’s just once per Node.)

class SCons.Taskmaster.Task(tm, targets, top, node)

Bases: abc.ABC

SCons build engine abstract task class.

This controls the interaction of the actual building of node and the rest of the engine.

This is expected to handle all of the normally-customizable aspects of controlling a build, so any given application should be able to do what it wants by sub-classing this class and overriding methods as appropriate. If an application needs to customize something by sub-classing Taskmaster (or some other build engine class), we should first try to migrate that functionality into this class.

Note that it’s generally a good idea for sub-classes to call these methods explicitly to update state, etc., rather than roll their own interaction with Taskmaster from scratch.

_abc_impl = <_abc_data object>

_exception_raise()

Raises a pending exception that was recorded while getting a Task ready for execution.

_no_exception_to_raise()

display(message)

Hook to allow the calling interface to display a message.

This hook gets called as part of preparing a task for execution (that is, a Node to be built). As part of figuring out what Node should be built next, the actual target list may be altered, along with a message describing the alteration. The calling interface can subclass Task and provide a concrete implementation of this method to see those messages.

exc_clear()

Clears any recorded exception.

This also changes the “exception_raise” attribute to point to the appropriate do-nothing method.

exc_info()

Returns info about a recorded exception.

exception_set(exception=None)

Records an exception to be raised at the appropriate time.

This also changes the “exception_raise” attribute to point to the method that will, in fact

execute()

Called to execute the task.

This method is called from multiple threads in a parallel build, so only do thread safe stuff here. Do thread unsafe stuff in prepare(), executed() or failed().

executed()

Called when the task has been successfully executed and the Taskmaster instance wants to call the Node’s callback methods.

This may have been a do-nothing operation (to preserve build order), so we must check the node’s state before deciding whether it was “built”, in which case we call the appropriate Node method. In any event, we always call “visited()”, which will handle any post-visit actions that must take place regardless of whether or not the target was an actual built target or a source Node.

executed_with_callbacks()

Called when the task has been successfully executed and the Taskmaster instance wants to call the Node’s callback methods.

This may have been a do-nothing operation (to preserve build order), so we must check the node’s state before deciding whether it was “built”, in which case we call the appropriate Node method. In any event, we always call “visited()”, which will handle any post-visit actions that must take place regardless of whether or not the target was an actual built target or a source Node.

executed_without_callbacks()

Called when the task has been successfully executed and the Taskmaster instance doesn’t want to call the Node’s callback methods.

fail_continue()

Explicit continue-the-build failure.

This sets failure status on the target nodes and all of their dependent parent nodes.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

fail_stop()

Explicit stop-the-build failure.

This sets failure status on the target nodes and all of their dependent parent nodes.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

failed()

Default action when a task fails: stop the build.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

get_target()

Fetch the target being built or updated by this task.

make_ready()

Marks all targets in a task ready for execution if any target is not current.

This is the default behavior for building only what’s necessary.

make_ready_all()

Marks all targets in a task ready for execution.

This is used when the interface needs every target Node to be visited–the canonical example being the “scons -c” option.

make_ready_current()

Marks all targets in a task ready for execution if any target is not current.

This is the default behavior for building only what’s necessary.

abstract needs_execute()

postprocess()

Post-processes a task after it’s been executed.

This examines all the targets just built (or not, we don’t care if the build was successful, or even if there was no build because everything was up-to-date) to see if they have any waiting parent Nodes, or Nodes waiting on a common side effect, that can be put back on the candidates list.

prepare()

Called just before the task is executed.

This is mainly intended to give the target Nodes a chance to unlink underlying files and make all necessary directories before the Action is actually called to build the targets.

trace_message(method, node, description='node')

class SCons.Taskmaster.Taskmaster(targets=[], tasker=None, order=None, trace=None)

Bases: object

The Taskmaster for walking the dependency DAG.

_find_next_ready_node()

Finds the next node that is ready to be built.

This is the main guts of the DAG walk. We loop through the list of candidates, looking for something that has no un-built children (i.e., that is a leaf Node or has dependencies that are all leaf Nodes or up-to-date). Candidate Nodes are re-scanned (both the target Node itself and its sources, which are always scanned in the context of a given target) to discover implicit dependencies. A Node that must wait for some children to be built will be put back on the candidates list after the children have finished building. A Node that has been put back on the candidates list in this way may have itself (or its sources) re-scanned, in order to handle generated header files (e.g.) and the implicit dependencies therein.

Note that this method does not do any signature calculation or up-to-date check itself. All of that is handled by the Task class. This is purely concerned with the dependency graph walk.

_validate_pending_children()

Validate the content of the pending_children set. Assert if an internal error is found.

This function is used strictly for debugging the taskmaster by checking that no invariants are violated. It is not used in normal operation.

The pending_children set is used to detect cycles in the dependency graph. We call a “pending child” a child that is found in the “pending” state when checking the dependencies of its parent node.

A pending child can occur when the Taskmaster completes a loop through a cycle. For example, let’s imagine a graph made of three nodes (A, B and C) making a cycle. The evaluation starts at node A. The Taskmaster first considers whether node A’s child B is up-to-date. Then, recursively, node B needs to check whether node C is up-to-date. This leaves us with a dependency graph looking like:

                      Next candidate                                                                       Node A (Pending) --> Node B(Pending) --> Node C (NoState)
^                                     |
|                                     |
+-------------------------------------+

Now, when the Taskmaster examines the Node C’s child Node A, it finds that Node A is in the “pending” state. Therefore, Node A is a pending child of node C.

Pending children indicate that the Taskmaster has potentially loop back through a cycle. We say potentially because it could also occur when a DAG is evaluated in parallel. For example, consider the following graph:

Node A (Pending) --> Node B(Pending) --> Node C (Pending) --> ...
        |                                     ^
        |                                     |
        +----------> Node D (NoState) --------+
                          /
          Next candidate /

The Taskmaster first evaluates the nodes A, B, and C and starts building some children of node C. Assuming, that the maximum parallel level has not been reached, the Taskmaster will examine Node D. It will find that Node C is a pending child of Node D.

In summary, evaluating a graph with a cycle will always involve a pending child at one point. A pending child might indicate either a cycle or a diamond-shaped DAG. Only a fraction of the nodes ends-up being a “pending child” of another node. This keeps the pending_children set small in practice.

We can differentiate between the two cases if we wait until the end of the build. At this point, all the pending children nodes due to a diamond-shaped DAG will have been properly built (or will have failed to build). But, the pending children involved in a cycle will still be in the pending state.

The taskmaster removes nodes from the pending_children set as soon as a pending_children node moves out of the pending state. This also helps to keep the pending_children set small.

cleanup()

Check for dependency cycles.

find_next_candidate()

Returns the next candidate Node for (potential) evaluation.

The candidate list (really a stack) initially consists of all of the top-level (command line) targets provided when the Taskmaster was initialized. While we walk the DAG, visiting Nodes, all the children that haven’t finished processing get pushed on to the candidate list. Each child can then be popped and examined in turn for whether their children are all up-to-date, in which case a Task will be created for their actual evaluation and potential building.

Here is where we also allow candidate Nodes to alter the list of Nodes that should be examined. This is used, for example, when invoking SCons in a source directory. A source directory Node can return its corresponding build directory Node, essentially saying, “Hey, you really need to build this thing over here instead.”

next_task()

Returns the next task to be executed.

This simply asks for the next Node to be evaluated, and then wraps it in the specific Task subclass with which we were initialized.

no_next_candidate()

Stops Taskmaster processing by not returning a next candidate.

Note that we have to clean-up the Taskmaster candidate list because the cycle detection depends on the fact all nodes have been processed somehow.

stop()

Stops the current build completely.

trace_message(message)

trace_node(node)

will_not_build(nodes, node_func=<function Taskmaster.<lambda>>)

Perform clean-up about nodes that will never be built. Invokes a user defined function on all of these nodes (including all of their parents).

SCons.Taskmaster.dump_stats()

SCons.Taskmaster.find_cycle(stack, visited)

SCons.Util module

Various SCons utility functions.

SCons.Util.AddMethod(obj, function, name=None)

Adds a method to an object.

Adds function to obj if obj is a class object. Adds function as a bound method if obj is an instance object. If obj looks like an environment instance, use MethodWrapper to add it. If name is supplied it is used as the name of function.

Although this works for any class object, the intent as a public API is to be used on Environment, to be able to add a method to all construction environments; it is preferred to use env.AddMethod to add to an individual environment.

>>> class A:
...    ...

>>> a = A()

>>> def f(self, x, y):
...    self.z = x + y

>>> AddMethod(A, f, "add")
>>> a.add(2, 4)
>>> print(a.z)
6
>>> a.data = ['a', 'b', 'c', 'd', 'e', 'f']
>>> AddMethod(a, lambda self, i: self.data[i], "listIndex")
>>> print(a.listIndex(3))
d

SCons.Util.AddPathIfNotExists(env_dict, key, path, sep=':')

Add a path element to a construction variable.

key is looked up in env_dict, and path is added to it if it is not already present. env_dict[key] is assumed to be in the format of a PATH variable: a list of paths separated by sep tokens. Example:

>>> env = {'PATH': '/bin:/usr/bin:/usr/local/bin'}
>>> AddPathIfNotExists(env, 'PATH', '/opt/bin')
>>> print(env['PATH'])
/opt/bin:/bin:/usr/bin:/usr/local/bin

SCons.Util.AppendPath(oldpath, newpath, sep=':', delete_existing=True, canonicalize=None) → Union[list, str]

Appends newpath path elements to oldpath.

Will only add any particular path once (leaving the last one it encounters and ignoring the rest, to preserve path order), and will os.path.normpath and os.path.normcase all paths to help assure this. This can also handle the case where oldpath is a list instead of a string, in which case a list will be returned instead of a string. For example:

>>> p = AppendPath("/foo/bar:/foo", "/biz/boom:/foo")
>>> print(p)
/foo/bar:/biz/boom:/foo

If delete_existing is False, then adding a path that exists will not move it to the end; it will stay where it is in the list.

>>> p = AppendPath("/foo/bar:/foo", "/biz/boom:/foo", delete_existing=False)
>>> print(p)
/foo/bar:/foo:/biz/boom

If canonicalize is not None, it is applied to each element of newpath before use.

class SCons.Util.CLVar(initlist=None)

Bases: collections.UserList

A container for command-line construction variables.

Forces the use of a list of strings intended as command-line arguments. Like collections.UserList, but the argument passed to the initializter will be processed by the Split() function, which includes special handling for string types: they will be split into a list of words, not coereced directly to a list. The same happens if a string is added to a CLVar, which allows doing the right thing with both Append()/Prepend() methods, as well as with pure Python addition, regardless of whether adding a list or a string to a construction variable.

Side effect: spaces will be stripped from individual string arguments. If you need spaces preserved, pass strings containing spaces inside a list argument.

>>> u = UserList("--some --opts and args")
>>> print(len(u), repr(u))
22 ['-', '-', 's', 'o', 'm', 'e', ' ', '-', '-', 'o', 'p', 't', 's', ' ', 'a', 'n', 'd', ' ', 'a', 'r', 'g', 's']
>>> c = CLVar("--some --opts and args")
>>> print(len(c), repr(c))
4 ['--some', '--opts', 'and', 'args']
>>> c += "    strips spaces    "
>>> print(len(c), repr(c))
6 ['--some', '--opts', 'and', 'args', 'strips', 'spaces']

_abc_impl = <_abc_data object>

append(item)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

copy()

count(value) → integer -- return number of occurrences of value

extend(other)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(item)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

sort(*args, **kwds)

class SCons.Util.Delegate(attribute)

Bases: object

A Python Descriptor class that delegates attribute fetches to an underlying wrapped subject of a Proxy. Typical use:

class Foo(Proxy):
    __str__ = Delegate('__str__')

class SCons.Util.DisplayEngine

Bases: object

A callable class used to display SCons messages.

print_it = True

set_mode(mode)

SCons.Util.IDX(n) → bool

Generate in index into strings from the tree legends.

These are always a choice between two, so bool works fine.

class SCons.Util.LogicalLines(fileobj)

Bases: object

Wrapper class for the logical_lines method.

Allows us to read all “logical” lines at once from a given file object.

readlines()

SCons.Util.MD5collect(signatures)

Deprecated. Use hash_collect() instead.

SCons.Util.MD5filesignature(fname, chunksize=65536)

Deprecated. Use hash_file_signature() instead.

SCons.Util.MD5signature(s)

Deprecated. Use hash_signature() instead.

class SCons.Util.MethodWrapper(obj, method, name=None)

Bases: object

A generic Wrapper class that associates a method with an object.

As part of creating this MethodWrapper object an attribute with the specified name (by default, the name of the supplied method) is added to the underlying object. When that new “method” is called, our __call__() method adds the object as the first argument, simulating the Python behavior of supplying “self” on method calls.

We hang on to the name by which the method was added to the underlying base class so that we can provide a method to “clone” ourselves onto a new underlying object being copied (without which we wouldn’t need to save that info).

clone(new_object)

Returns an object that re-binds the underlying “method” to the specified new object.

class SCons.Util.NodeList(initlist=None)

Bases: collections.UserList

A list of Nodes with special attribute retrieval.

Unlike an ordinary list, access to a member’s attribute returns a NodeList containing the same attribute for each member. Although this can hold any object, it is intended for use when processing Nodes, where fetching an attribute of each member is very commone, for example getting the content signature of each node. The term “attribute” here includes the string representation.

Example:

>>> someList = NodeList(['  foo  ', '  bar  '])
>>> someList.strip()
['foo', 'bar']

__getattr__(name) → SCons.Util.NodeList

Returns a NodeList of name from each member.

__getitem__(index)

Returns one item, forces a NodeList if index is a slice.

_abc_impl = <_abc_data object>

append(item)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

copy()

count(value) → integer -- return number of occurrences of value

extend(other)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(item)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

sort(*args, **kwds)

class SCons.Util.Null(*args, **kwargs)

Bases: object

Null objects always and reliably “do nothing.”

class SCons.Util.NullSeq(*args, **kwargs)

Bases: SCons.Util.Null

A Null object that can also be iterated over.

SCons.Util.PrependPath(oldpath, newpath, sep=':', delete_existing=True, canonicalize=None) → Union[list, str]

Prepends newpath path elements to oldpath.

Will only add any particular path once (leaving the first one it encounters and ignoring the rest, to preserve path order), and will os.path.normpath and os.path.normcase all paths to help assure this. This can also handle the case where oldpath is a list instead of a string, in which case a list will be returned instead of a string. For example:

>>> p = PrependPath("/foo/bar:/foo", "/biz/boom:/foo")
>>> print(p)
/biz/boom:/foo:/foo/bar

If delete_existing is False, then adding a path that exists will not move it to the beginning; it will stay where it is in the list.

>>> p = PrependPath("/foo/bar:/foo", "/biz/boom:/foo", delete_existing=False)
>>> print(p)
/biz/boom:/foo/bar:/foo

If canonicalize is not None, it is applied to each element of newpath before use.

class SCons.Util.Proxy(subject)

Bases: object

A simple generic Proxy class, forwarding all calls to subject.

This means you can take an object, let’s call it ‘obj_a, and wrap it in this Proxy class, with a statement like this:

proxy_obj = Proxy(obj_a)

Then, if in the future, you do something like this:

x = proxy_obj.var1

since the Proxy class does not have a var1 attribute (but presumably objA does), the request actually is equivalent to saying:

x = obj_a.var1

Inherit from this class to create a Proxy.

With Python 3.5+ this does not work transparently for Proxy subclasses that use special .__*__() method names, because those names are now bound to the class, not the individual instances. You now need to know in advance which special method names you want to pass on to the underlying Proxy object, and specifically delegate their calls like this:

class Foo(Proxy):
    __str__ = Delegate('__str__')

__getattr__(name)

Retrieve an attribute from the wrapped object.

Raises

AttributeError – if attribute name doesn’t exist.

get()

Retrieve the entire wrapped object

SCons.Util.RegError

alias of SCons.Util._NoError

SCons.Util.RegGetValue(root, key)

SCons.Util.RegOpenKeyEx(root, key)

class SCons.Util.Selector

Bases: collections.OrderedDict

A callable ordered dictionary that maps file suffixes to dictionary values. We preserve the order in which items are added so that get_suffix() calls always return the first suffix added.

clear() → None.  Remove all items from od.

copy() → a shallow copy of od

fromkeys(value=None)

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

move_to_end(key, last=True)

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

pop(k[, d]) → v, remove specified key and return the corresponding

value. If key is not found, d is returned if given, otherwise KeyError is raised.

popitem(last=True)

Remove and return a (key, value) pair from the dictionary.

Pairs are returned in LIFO order if last is true or FIFO order if false.

setdefault(key, default=None)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

SCons.Util.Split(arg) → list

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. 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.

>>> print(Split(" this  is  a  string  "))
['this', 'is', 'a', 'string']
>>> print(Split(["stringlist", " preserving ", " spaces "]))
['stringlist', ' preserving ', ' spaces ']

class SCons.Util.Unbuffered(file)

Bases: object

A proxy that wraps a file object, flushing after every write.

Delegates everything else to the wrapped object.

write(arg)

writelines(arg)

class SCons.Util.UniqueList(initlist=None)

Bases: collections.UserList

A list which maintains uniqueness.

Uniquing is lazy: rather than being assured on list changes, it is fixed up on access by those methods which need to act on a uniqe list to be correct. That means things like “in” don’t have to eat the uniquing time.

__make_unique()

_abc_impl = <_abc_data object>

append(item)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

copy()

count(value) → integer -- return number of occurrences of value

extend(other)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(item)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

sort(*args, **kwds)

SCons.Util.WhereIs(file, path=None, pathext=None, reject=None) → Optional[str]

Return the path to an executable that matches file.

Searches the given path for file, respecting any filename extensions pathext (on the Windows platform only), and returns the full path to the matching command. If no command is found, return None.

If path is not specified, os.environ[PATH] is used. If pathext is not specified, os.environ[PATHEXT] is used. Will not select any path name or names in the optional reject list.

exception SCons.Util._NoError

Bases: Exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

SCons.Util._attempt_get_hash_function(hash_name, hashlib_used=<module 'hashlib' from '/opt/local/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/hashlib.py'>, sys_used=<module 'sys' (built-in)>)

Wrapper used to try to initialize a hash function given.

If successful, returns the name of the hash function back to the user.

Otherwise returns None.

SCons.Util._attempt_init_of_python_3_9_hash_object(hash_function_object, sys_used=<module 'sys' (built-in)>)

Python 3.9 and onwards lets us initialize the hash function object with the key “usedforsecurity”=false. This lets us continue to use algorithms that have been deprecated either by FIPS or by Python itself, as the MD5 algorithm SCons prefers is not being used for security purposes as much as a short, 32 char hash that is resistant to accidental collisions.

In prior versions of python, hashlib returns a native function wrapper, which errors out when it’s queried for the optional parameter, so this function wraps that call.

It can still throw a ValueError if the initialization fails due to FIPS compliance issues, but that is assumed to be the responsibility of the caller.

SCons.Util._get_hash_object(hash_format, hashlib_used=<module 'hashlib' from '/opt/local/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/hashlib.py'>, sys_used=<module 'sys' (built-in)>)

Allocates a hash object using the requested hash format.

Parameters

hash_format – Hash format to use.

Returns

hashlib object.

SCons.Util._semi_deepcopy_list(obj) → list

SCons.Util._semi_deepcopy_tuple(obj) → tuple

SCons.Util._set_allowed_viable_default_hashes(hashlib_used, sys_used=<module 'sys' (built-in)>)

Checks if SCons has ability to call the default algorithms normally supported.

This util class is sometimes called prior to setting the user-selected hash algorithm, meaning that on FIPS-compliant systems the library would default-initialize MD5 and throw an exception in set_hash_format. A common case is using the SConf options, which can run prior to main, and thus ignore the options.hash_format variable.

This function checks the DEFAULT_HASH_FORMATS and sets the ALLOWED_HASH_FORMATS to only the ones that can be called. In Python >= 3.9 this will always default to MD5 as in Python 3.9 there is an optional attribute “usedforsecurity” set for the method.

Throws if no allowed hash formats are detected.

SCons.Util._show_md5_warning(function_name)

Shows a deprecation warning for various MD5 functions.

SCons.Util.adjustixes(fname, pre, suf, ensure_suffix=False) → str

Adjust filename prefixes and suffixes as needed.

Add prefix to fname if specified. Add suffix to fname if specified and if ensure_suffix is True

SCons.Util.case_sensitive_suffixes(s1, s2) → bool

SCons.Util.cmp(a, b) → bool

A cmp function because one is no longer available in python3.

SCons.Util.containsAll(s, pat) → bool

Check whether string s contains ALL of the items in pat.

SCons.Util.containsAny(s, pat) → bool

Check whether string s contains ANY of the items in pat.

SCons.Util.containsOnly(s, pat) → bool

Check whether string s contains ONLY items in pat.

SCons.Util.dictify(keys, values, result=None) → dict

SCons.Util.do_flatten(sequence, result, isinstance=<built-in function isinstance>, StringTypes=(<class 'str'>, <class 'collections.UserString'>), SequenceTypes=(<class 'list'>, <class 'tuple'>, <class 'collections.UserList'>, <class 'collections.abc.MappingView'>))

SCons.Util.flatten(obj, isinstance=<built-in function isinstance>, StringTypes=(<class 'str'>, <class 'collections.UserString'>), SequenceTypes=(<class 'list'>, <class 'tuple'>, <class 'collections.UserList'>, <class 'collections.abc.MappingView'>), do_flatten=<function do_flatten>) → list

Flatten a sequence to a non-nested list.

Converts either a single scalar or a nested sequence to a non-nested list. Note that flatten() considers strings to be scalars instead of sequences like pure Python would.

SCons.Util.flatten_sequence(sequence, isinstance=<built-in function isinstance>, StringTypes=(<class 'str'>, <class 'collections.UserString'>), SequenceTypes=(<class 'list'>, <class 'tuple'>, <class 'collections.UserList'>, <class 'collections.abc.MappingView'>), do_flatten=<function do_flatten>) → list

Flatten a sequence to a non-nested list.

Same as flatten(), but it does not handle the single scalar case. This is slightly more efficient when one knows that the sequence to flatten can not be a scalar.

SCons.Util.get_current_hash_algorithm_used()

Returns the current hash algorithm name used.

Where the python version >= 3.9, this is expected to return md5. If python’s version is <= 3.8, this returns md5 on non-FIPS-mode platforms, and sha1 or sha256 on FIPS-mode Linux platforms.

This function is primarily useful for testing, where one expects a value to be one of N distinct hashes, and therefore the test needs to know which hash to select.

SCons.Util.get_env_bool(env, name, default=False) → bool

Convert a construction variable to bool.

If the value of name in env is ‘true’, ‘yes’, ‘y’, ‘on’ (case insensitive) or anything convertible to int that yields non-zero then return True; if ‘false’, ‘no’, ‘n’, ‘off’ (case insensitive) or a number that converts to integer zero return False. Otherwise, return default.

Parameters

• env – construction environment, or any dict-like object

• name – name of the variable

• default – value to return if name not in env or cannot be converted (default: False)

Returns

the “truthiness” of name

SCons.Util.get_environment_var(varstr) → Optional[str]

Return undecorated construction variable string.

Determine if varstr looks like a reference to a single environment variable, like “$FOO” or “${FOO}”. If so, return that variable with no decorations, like “FOO”. If not, return None.

SCons.Util.get_hash_format()

Retrieves the hash format or None if not overridden.

A return value of None does not guarantee that MD5 is being used; instead, it means that the default precedence order documented in SCons.Util.set_hash_format() is respected.

SCons.Util.get_native_path(path) → str

Transform an absolute path into a native path for the system.

In Cygwin, this converts from a Cygwin path to a Windows path, without regard to whether path refers to an existing file system object. For other platforms, path is unchanged.

SCons.Util.get_os_env_bool(name, default=False) → bool

Convert an environment variable to bool.

Conversion is the same as for get_env_bool().

SCons.Util.hash_collect(signatures, hash_format=None)

Collects a list of signatures into an aggregate signature.

Parameters

• signatures – a list of signatures

• hash_format – Specify to override default hash format

Returns

the aggregate signature

SCons.Util.hash_file_signature(fname, chunksize=65536, hash_format=None)

Generate the md5 signature of a file

Parameters

• fname – file to hash

• chunksize – chunk size to read

• hash_format – Specify to override default hash format

Returns

String of Hex digits representing the signature

SCons.Util.hash_signature(s, hash_format=None)

Generate hash signature of a string

Parameters

• s – either string or bytes. Normally should be bytes

• hash_format – Specify to override default hash format

Returns

String of hex digits representing the signature

SCons.Util.is_Dict(obj, isinstance=<built-in function isinstance>, DictTypes=(<class 'dict'>, <class 'collections.UserDict'>)) → bool

SCons.Util.is_List(obj, isinstance=<built-in function isinstance>, ListTypes=(<class 'list'>, <class 'collections.UserList'>)) → bool

SCons.Util.is_Scalar(obj, isinstance=<built-in function isinstance>, StringTypes=(<class 'str'>, <class 'collections.UserString'>), SequenceTypes=(<class 'list'>, <class 'tuple'>, <class 'collections.UserList'>, <class 'collections.abc.MappingView'>)) → bool

SCons.Util.is_Sequence(obj, isinstance=<built-in function isinstance>, SequenceTypes=(<class 'list'>, <class 'tuple'>, <class 'collections.UserList'>, <class 'collections.abc.MappingView'>)) → bool

SCons.Util.is_String(obj, isinstance=<built-in function isinstance>, StringTypes=(<class 'str'>, <class 'collections.UserString'>)) → bool

SCons.Util.is_Tuple(obj, isinstance=<built-in function isinstance>, tuple=<class 'tuple'>) → bool

SCons.Util.logical_lines(physical_lines, joiner=<built-in method join of str object>)

SCons.Util.make_path_relative(path) → str

Converts an absolute path name to a relative pathname.

SCons.Util.print_time()

Hack to return a value from Main if can’t import Main.

SCons.Util.print_tree(root, child_func, prune=0, showtags=False, margin=[0], visited=None, lastChild=False, singleLineDraw=False)

Print a tree of nodes.

This is like func:render_tree, except it prints lines directly instead of creating a string representation in memory, so that huge trees can be handled.

Parameters

• root – the root node of the tree

• child_func – the function called to get the children of a node

• prune – don’t visit the same node twice

• showtags – print status information to the left of each node line

• margin – the format of the left margin to use for children of root. 1 results in a pipe, and 0 results in no pipe.

• visited – a dictionary of visited nodes in the current branch if prune` is 0, or in the whole tree if prune is 1.

• singleLineDraw – use line-drawing characters rather than ASCII.

SCons.Util.render_tree(root, child_func, prune=0, margin=[0], visited=None)

Render a tree of nodes into an ASCII tree view.

Parameters

• root – the root node of the tree

• child_func – the function called to get the children of a node

• prune – don’t visit the same node twice

• margin – the format of the left margin to use for children of root. 1 results in a pipe, and 0 results in no pipe.

• visited – a dictionary of visited nodes in the current branch if prune is 0, or in the whole tree if prune is 1.

SCons.Util.rightmost_separator(path, sep)

SCons.Util.semi_deepcopy(obj)

SCons.Util.semi_deepcopy_dict(obj, exclude=None) → dict

SCons.Util.set_hash_format(hash_format, hashlib_used=<module 'hashlib' from '/opt/local/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/hashlib.py'>, sys_used=<module 'sys' (built-in)>)

Sets the default hash format used by SCons.

If hash_format is None or an empty string, the default is determined by this function.

Currently the default behavior is to use the first available format of the following options: MD5, SHA1, SHA256.

SCons.Util.silent_intern(x)

Perform sys.intern on the passed argument and return the result. If the input is ineligible for interning the original argument is returned and no exception is thrown.

SCons.Util.splitext(path) → tuple

Split path into a (root, ext) pair.

Same as os.path.splitext but faster.

SCons.Util.to_String(obj, isinstance=<built-in function isinstance>, str=<class 'str'>, UserString=<class 'collections.UserString'>, BaseStringTypes=<class 'str'>) → str

Return a string version of obj.

SCons.Util.to_String_for_signature(obj, to_String_for_subst=<function to_String_for_subst>, AttributeError=<class 'AttributeError'>) → str

Return a string version of obj for signature usage.

Like to_String_for_subst() but has special handling for scons objects that have a for_signature() method, and for dicts.

SCons.Util.to_String_for_subst(obj, isinstance=<built-in function isinstance>, str=<class 'str'>, BaseStringTypes=<class 'str'>, SequenceTypes=(<class 'list'>, <class 'tuple'>, <class 'collections.UserList'>, <class 'collections.abc.MappingView'>), UserString=<class 'collections.UserString'>) → str

Return a string version of obj for subst usage.

SCons.Util.to_bytes(s) → bytes

SCons.Util.to_str(s) → str

SCons.Util.unique(seq)

Return a list of the elements in seq without duplicates, ignoring order.

>>> mylist = unique([1, 2, 3, 1, 2, 3])
>>> print(sorted(mylist))
[1, 2, 3]
>>> mylist = unique("abcabc")
>>> print(sorted(mylist))
['a', 'b', 'c']
>>> mylist = unique(([1, 2], [2, 3], [1, 2]))
>>> print(sorted(mylist))
[[1, 2], [2, 3]]

For best speed, all sequence elements should be hashable. Then unique() will usually work in linear time.

If not possible, the sequence elements should enjoy a total ordering, and if list(s).sort() doesn’t raise TypeError it’s assumed that they do enjoy a total ordering. Then unique() will usually work in O(N*log2(N)) time.

If that’s not possible either, the sequence elements must support equality-testing. Then unique() will usually work in quadratic time.

SCons.Util.uniquer(seq, idfun=None)

SCons.Util.uniquer_hashables(seq)

SCons.Util.updrive(path) → str

Make the drive letter (if any) upper case.

This is useful because Windows is inconsistent on the case of the drive letter, which can cause inconsistencies when calculating command signatures.

SCons.Util.wait_for_process_to_die(pid)

Wait for specified process to die, or alternatively kill it NOTE: This function operates best with psutil pypi package TODO: Add timeout which raises exception

SCons.Warnings module

The SCons warnings framework.

exception SCons.Warnings.CacheVersionWarning

Bases: SCons.Warnings.WarningOnByDefault

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.CacheWriteErrorWarning

Bases: SCons.Warnings.SConsWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.CorruptSConsignWarning

Bases: SCons.Warnings.WarningOnByDefault

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.DependencyWarning

Bases: SCons.Warnings.SConsWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.DeprecatedDebugOptionsWarning

Bases: SCons.Warnings.MandatoryDeprecatedWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.DeprecatedMissingSConscriptWarning

Bases: SCons.Warnings.DeprecatedWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.DeprecatedOptionsWarning

Bases: SCons.Warnings.MandatoryDeprecatedWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.DeprecatedSourceCodeWarning

Bases: SCons.Warnings.FutureDeprecatedWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.DeprecatedWarning

Bases: SCons.Warnings.SConsWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.DevelopmentVersionWarning

Bases: SCons.Warnings.WarningOnByDefault

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.DuplicateEnvironmentWarning

Bases: SCons.Warnings.WarningOnByDefault

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.FortranCxxMixWarning

Bases: SCons.Warnings.LinkWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.FutureDeprecatedWarning

Bases: SCons.Warnings.SConsWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.FutureReservedVariableWarning

Bases: SCons.Warnings.WarningOnByDefault

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.LinkWarning

Bases: SCons.Warnings.WarningOnByDefault

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.MandatoryDeprecatedWarning

Bases: SCons.Warnings.DeprecatedWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.MisleadingKeywordsWarning

Bases: SCons.Warnings.WarningOnByDefault

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.MissingSConscriptWarning

Bases: SCons.Warnings.WarningOnByDefault

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.NoObjectCountWarning

Bases: SCons.Warnings.WarningOnByDefault

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.NoParallelSupportWarning

Bases: SCons.Warnings.WarningOnByDefault

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.PythonVersionWarning

Bases: SCons.Warnings.DeprecatedWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.ReservedVariableWarning

Bases: SCons.Warnings.WarningOnByDefault

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.SConsWarning

Bases: SCons.Errors.UserError

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.StackSizeWarning

Bases: SCons.Warnings.WarningOnByDefault

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.TargetNotBuiltWarning

Bases: SCons.Warnings.SConsWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.TaskmasterNeedsExecuteWarning

Bases: SCons.Warnings.DeprecatedWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.ToolQtDeprecatedWarning

Bases: SCons.Warnings.FutureDeprecatedWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.VisualCMissingWarning

Bases: SCons.Warnings.WarningOnByDefault

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.VisualStudioMissingWarning

Bases: SCons.Warnings.SConsWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.VisualVersionMismatch

Bases: SCons.Warnings.WarningOnByDefault

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception SCons.Warnings.WarningOnByDefault

Bases: SCons.Warnings.SConsWarning

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

SCons.Warnings.enableWarningClass(clazz)

Enables all warnings of type clazz or derived from clazz.

SCons.Warnings.process_warn_strings(arguments)

Process requests to enable/disable warnings.

The requests are strings passed to the –warn option or the SetOption(‘warn’) function.

An argument to this option should be of the form “warning-class” or “no-warning-class”. The warning class is munged and has the suffix “Warning” added in order to get an actual class name from the classes above, which we need to pass to the {enable,disable}WarningClass() functions.

For example, “deprecated” will enable the DeprecatedWarning class. “no-dependency” will disable the DependencyWarning class.

As a special case, –warn=all and –warn=no-all will enable or disable (respectively) the base class of all SCons warnings.

SCons.Warnings.suppressWarningClass(clazz)

Suppresses all warnings of type clazz or derived from clazz.

SCons.Warnings.warn(clazz, *args)

Issue a warning, accounting for SCons rules.

Check if warnings for this class are enabled. If warnings are treated as exceptions, raise exception. Use the global warning-emitter _warningOut, which allows selecting different ways of presenting a traceback (see Script/Main.py)

SCons.Warnings.warningAsException(flag=True)

Set global _warningAsExeption flag.

Parameters

flag – value to set warnings-as-exceptions to [default: True]

Returns

The previous value.

SCons.cpp module

SCons C Pre-Processor module

SCons.cpp.CPP_to_Python(s)

Converts a C pre-processor expression into an equivalent Python expression that can be evaluated.

SCons.cpp.CPP_to_Python_Ops_Sub(m)

SCons.cpp.Cleanup_CPP_Expressions(ts)

class SCons.cpp.DumbPreProcessor(*args, **kw)

Bases: SCons.cpp.PreProcessor

A preprocessor that ignores all #if/#elif/#else/#endif directives and just reports back all of the #include files (like the classic SCons scanner did).

This is functionally equivalent to using a regular expression to find all of the #include lines, only slower. It exists mainly as an example of how the main PreProcessor class can be sub-classed to tailor its behavior.

__call__(file)

Pre-processes a file.

This is the main public entry point.

_do_if_else_condition(condition)

Common logic for evaluating the conditions on #if, #ifdef and #ifndef lines.

_match_tuples(tuples)

_parse_tuples(contents)

_process_tuples(tuples, file=None)

all_include(t)

do_define(t)

Default handling of a #define line.

do_elif(t)

Default handling of a #elif line.

do_else(t)

Default handling of a #else line.

do_endif(t)

Default handling of a #endif line.

do_if(t)

Default handling of a #if line.

do_ifdef(t)

Default handling of a #ifdef line.

do_ifndef(t)

Default handling of a #ifndef line.

do_import(t)

Default handling of a #import line.

do_include(t)

Default handling of a #include line.

do_include_next(t)

Default handling of a #include line.

do_nothing(t)

Null method for when we explicitly want the action for a specific preprocessor directive to do nothing.

do_undef(t)

Default handling of a #undef line.

eval_expression(t)

Evaluates a C preprocessor expression.

This is done by converting it to a Python equivalent and eval()ing it in the C preprocessor namespace we use to track #define values.

finalize_result(fname)

find_include_file(t)

Finds the #include file for a given preprocessor tuple.

initialize_result(fname)

process_contents(contents)

Pre-processes a file contents.

Is used by tests

process_file(file)

Pre-processes a file.

This is the main internal entry point.

read_file(file)

resolve_include(t)

Resolve a tuple-ized #include line.

This handles recursive expansion of values without “” or <> surrounding the name until an initial ” or < is found, to handle #include FILE where FILE is a #define somewhere else.

restore()

Pops the previous dispatch table off the stack and makes it the current one.

save()

Pushes the current dispatch table on the stack and re-initializes the current dispatch table to the default.

scons_current_file(t)

start_handling_includes(t=None)

Causes the PreProcessor object to start processing #import, #include and #include_next lines.

This method will be called when a #if, #ifdef, #ifndef or #elif evaluates True, or when we reach the #else in a #if, #ifdef, #ifndef or #elif block where a condition already evaluated False.

stop_handling_includes(t=None)

Causes the PreProcessor object to stop processing #import, #include and #include_next lines.

This method will be called when a #if, #ifdef, #ifndef or #elif evaluates False, or when we reach the #else in a #if, #ifdef, #ifndef or #elif block where a condition already evaluated True.

tupleize(contents)

Turns the contents of a file into a list of easily-processed tuples describing the CPP lines in the file.

The first element of each tuple is the line’s preprocessor directive (#if, #include, #define, etc., minus the initial ‘#’). The remaining elements are specific to the type of directive, as pulled apart by the regular expression.

class SCons.cpp.FunctionEvaluator(name, args, expansion)

Bases: object

Handles delayed evaluation of a #define function call.

__call__(*values)

Evaluates the expansion of a #define macro function called with the specified values.

class SCons.cpp.PreProcessor(current='.', cpppath=(), dict={}, all=0, depth=- 1)

Bases: object

The main workhorse class for handling C pre-processing.

__call__(file)

Pre-processes a file.

This is the main public entry point.

_do_if_else_condition(condition)

Common logic for evaluating the conditions on #if, #ifdef and #ifndef lines.

_match_tuples(tuples)

_parse_tuples(contents)

_process_tuples(tuples, file=None)

all_include(t)

do_define(t)

Default handling of a #define line.

do_elif(t)

Default handling of a #elif line.

do_else(t)

Default handling of a #else line.

do_endif(t)

Default handling of a #endif line.

do_if(t)

Default handling of a #if line.

do_ifdef(t)

Default handling of a #ifdef line.

do_ifndef(t)

Default handling of a #ifndef line.

do_import(t)

Default handling of a #import line.

do_include(t)

Default handling of a #include line.

do_include_next(t)

Default handling of a #include line.

do_nothing(t)

Null method for when we explicitly want the action for a specific preprocessor directive to do nothing.

do_undef(t)

Default handling of a #undef line.

eval_expression(t)

Evaluates a C preprocessor expression.

This is done by converting it to a Python equivalent and eval()ing it in the C preprocessor namespace we use to track #define values.

finalize_result(fname)

find_include_file(t)

Finds the #include file for a given preprocessor tuple.

initialize_result(fname)

process_contents(contents)

Pre-processes a file contents.

Is used by tests

process_file(file)

Pre-processes a file.

This is the main internal entry point.

read_file(file)

resolve_include(t)

Resolve a tuple-ized #include line.

This handles recursive expansion of values without “” or <> surrounding the name until an initial ” or < is found, to handle #include FILE where FILE is a #define somewhere else.

restore()

Pops the previous dispatch table off the stack and makes it the current one.

save()

Pushes the current dispatch table on the stack and re-initializes the current dispatch table to the default.

scons_current_file(t)

start_handling_includes(t=None)

Causes the PreProcessor object to start processing #import, #include and #include_next lines.

This method will be called when a #if, #ifdef, #ifndef or #elif evaluates True, or when we reach the #else in a #if, #ifdef, #ifndef or #elif block where a condition already evaluated False.

stop_handling_includes(t=None)

Causes the PreProcessor object to stop processing #import, #include and #include_next lines.

This method will be called when a #if, #ifdef, #ifndef or #elif evaluates False, or when we reach the #else in a #if, #ifdef, #ifndef or #elif block where a condition already evaluated True.

tupleize(contents)

Turns the contents of a file into a list of easily-processed tuples describing the CPP lines in the file.

The first element of each tuple is the line’s preprocessor directive (#if, #include, #define, etc., minus the initial ‘#’). The remaining elements are specific to the type of directive, as pulled apart by the regular expression.

SCons.dblite module

dblite.py module contributed by Ralf W. Grosse-Kunstleve. Extended for Unicode by Steven Knight.

SCons.dblite._exercise()

class SCons.dblite.dblite(file_base_name, flag, mode)

Bases: object

Squirrel away references to the functions in various modules that we’ll use when our __del__() method calls our sync() method during shutdown. We might get destroyed when Python is in the midst of tearing down the different modules we import in an essentially arbitrary order, and some of the various modules’s global attributes may already be wiped out from under us.

See the discussion at:

http://mail.python.org/pipermail/python-bugs-list/2003-March/016877.html

_check_writable()

_open(mode='r', buffering=- 1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

Open file and return a stream. Raise OSError upon failure.

file is either a text or byte string giving the name (and the path if the file isn’t in the current working directory) of the file to be opened or an integer file descriptor of the file to be wrapped. (If a file descriptor is given, it is closed when the returned I/O object is closed, unless closefd is set to False.)

mode is an optional string that specifies the mode in which the file is opened. It defaults to ‘r’ which means open for reading in text mode. Other common values are ‘w’ for writing (truncating the file if it already exists), ‘x’ for creating and writing to a new file, and ‘a’ for appending (which on some Unix systems, means that all writes append to the end of the file regardless of the current seek position). In text mode, if encoding is not specified the encoding used is platform dependent: locale.getpreferredencoding(False) is called to get the current locale encoding. (For reading and writing raw bytes use binary mode and leave encoding unspecified.) The available modes are:

Character	Meaning
‘r’	open for reading (default)
‘w’	open for writing, truncating the file first
‘x’	create a new file and open it for writing
‘a’	open for writing, appending to the end of the file if it exists
‘b’	binary mode
‘t’	text mode (default)
‘+’	open a disk file for updating (reading and writing)
‘U’	universal newline mode (deprecated)

The default mode is ‘rt’ (open for reading text). For binary random access, the mode ‘w+b’ opens and truncates the file to 0 bytes, while ‘r+b’ opens the file without truncation. The ‘x’ mode implies ‘w’ and raises an FileExistsError if the file already exists.

Python distinguishes between files opened in binary and text modes, even when the underlying operating system doesn’t. Files opened in binary mode (appending ‘b’ to the mode argument) return contents as bytes objects without any decoding. In text mode (the default, or when ‘t’ is appended to the mode argument), the contents of the file are returned as strings, the bytes having been first decoded using a platform-dependent encoding or using the specified encoding if given.

‘U’ mode is deprecated and will raise an exception in future versions of Python. It has no effect in Python 3. Use newline to control universal newlines mode.

buffering is an optional integer used to set the buffering policy. Pass 0 to switch buffering off (only allowed in binary mode), 1 to select line buffering (only usable in text mode), and an integer > 1 to indicate the size of a fixed-size chunk buffer. When no buffering argument is given, the default buffering policy works as follows:

• Binary files are buffered in fixed-size chunks; the size of the buffer is chosen using a heuristic trying to determine the underlying device’s “block size” and falling back on io.DEFAULT_BUFFER_SIZE. On many systems, the buffer will typically be 4096 or 8192 bytes long.

• “Interactive” text files (files for which isatty() returns True) use line buffering. Other text files use the policy described above for binary files.

encoding is the name of the encoding used to decode or encode the file. This should only be used in text mode. The default encoding is platform dependent, but any encoding supported by Python can be passed. See the codecs module for the list of supported encodings.

errors is an optional string that specifies how encoding errors are to be handled—this argument should not be used in binary mode. Pass ‘strict’ to raise a ValueError exception if there is an encoding error (the default of None has the same effect), or pass ‘ignore’ to ignore errors. (Note that ignoring encoding errors can lead to data loss.) See the documentation for codecs.register or run ‘help(codecs.Codec)’ for a list of the permitted encoding error strings.

newline controls how universal newlines works (it only applies to text mode). It can be None, ‘’, ‘n’, ‘r’, and ‘rn’. It works as follows:

• On input, if newline is None, universal newlines mode is enabled. Lines in the input can end in ‘n’, ‘r’, or ‘rn’, and these are translated into ‘n’ before being returned to the caller. If it is ‘’, universal newline mode is enabled, but line endings are returned to the caller untranslated. If it has any of the other legal values, input lines are only terminated by the given string, and the line ending is returned to the caller untranslated.

• On output, if newline is None, any ‘n’ characters written are translated to the system default line separator, os.linesep. If newline is ‘’ or ‘n’, no translation takes place. If newline is any of the other legal values, any ‘n’ characters written are translated to the given string.

If closefd is False, the underlying file descriptor will be kept open when the file is closed. This does not work when a file name is given and must be True in that case.

A custom opener can be used by passing a callable as opener. The underlying file descriptor for the file object is then obtained by calling opener with (file, flags). opener must return an open file descriptor (passing os.open as opener results in functionality similar to passing None).

open() returns a file object whose type depends on the mode, and through which the standard file operations such as reading and writing are performed. When open() is used to open a file in a text mode (‘w’, ‘r’, ‘wt’, ‘rt’, etc.), it returns a TextIOWrapper. When used to open a file in a binary mode, the returned class varies: in read binary mode, it returns a BufferedReader; in write binary and append binary modes, it returns a BufferedWriter, and in read/write mode, it returns a BufferedRandom.

It is also possible to use a string or bytearray as a file for both reading and writing. For strings StringIO can be used like a file opened in a text mode, and for bytes a BytesIO can be used like a file opened in a binary mode.

_os_chmod(mode, *, dir_fd=None, follow_symlinks=True)

Change the access permissions of a file.

path

Path to be modified. May always be specified as a str, bytes, or a path-like object. On some platforms, path may also be specified as an open file descriptor. If this functionality is unavailable, using it raises an exception.

mode

Operating-system mode bitfield.

dir_fd

If not None, it should be a file descriptor open to a directory, and path should be relative; path will then be relative to that directory.

follow_symlinks

If False, and the last element of the path is a symbolic link, chmod will modify the symbolic link itself instead of the file the link points to.

It is an error to use dir_fd or follow_symlinks when specifying path as

an open file descriptor.

dir_fd and follow_symlinks may not be implemented on your platform.

If they are unavailable, using them will raise a NotImplementedError.

_os_chown(uid, gid, *, dir_fd=None, follow_symlinks=True)

Change the owner and group id of path to the numeric uid and gid.

path

Path to be examined; can be string, bytes, a path-like object, or open-file-descriptor int.

dir_fd

If not None, it should be a file descriptor open to a directory, and path should be relative; path will then be relative to that directory.

follow_symlinks

If False, and the last element of the path is a symbolic link, stat will examine the symbolic link itself instead of the file the link points to.

path may always be specified as a string. On some platforms, path may also be specified as an open file descriptor.

If this functionality is unavailable, using it raises an exception.

If dir_fd is not None, it should be a file descriptor open to a directory,

and path should be relative; path will then be relative to that directory.

If follow_symlinks is False, and the last element of the path is a symbolic

link, chown will modify the symbolic link itself instead of the file the link points to.

It is an error to use dir_fd or follow_symlinks when specifying path as

an open file descriptor.

dir_fd and follow_symlinks may not be implemented on your platform.

If they are unavailable, using them will raise a NotImplementedError.

_os_replace(dst, *, src_dir_fd=None, dst_dir_fd=None)

Rename a file or directory, overwriting the destination.

If either src_dir_fd or dst_dir_fd is not None, it should be a file

descriptor open to a directory, and the respective path string (src or dst) should be relative; the path will then be relative to that directory.

src_dir_fd and dst_dir_fd, may not be implemented on your platform.

If they are unavailable, using them will raise a NotImplementedError.

static _pickle_dump(obj, file, protocol=None, *, fix_imports=True)

Write a pickled representation of obj to the open file object file.

This is equivalent to Pickler(file, protocol).dump(obj), but may be more efficient.

The optional protocol argument tells the pickler to use the given protocol supported protocols are 0, 1, 2, 3 and 4. The default protocol is 3; a backward-incompatible protocol designed for Python 3.

Specifying a negative protocol version selects the highest protocol version supported. The higher the protocol used, the more recent the version of Python needed to read the pickle produced.

The file argument must have a write() method that accepts a single bytes argument. It can thus be a file object opened for binary writing, an io.BytesIO instance, or any other custom object that meets this interface.

If fix_imports is True and protocol is less than 3, pickle will try to map the new Python 3 names to the old module names used in Python 2, so that the pickle data stream is readable with Python 2.

_pickle_protocol = 4

_shutil_copyfile(dst, *, follow_symlinks=True)

Copy data from src to dst.

If follow_symlinks is not set and src is a symbolic link, a new symlink will be created instead of copying the file it points to.

_time_time()

time() -> floating point number

Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them.

close()

keys()

sync()

SCons.dblite.open(file, flag=None, mode=438)

SCons.exitfuncs module

Register functions which are executed when SCons exits for any reason.

SCons.exitfuncs._run_exitfuncs()

run any registered exit functions

_exithandlers is traversed in reverse order so functions are executed last in, first out.

SCons.exitfuncs.register(func, *targs, **kargs)

register a function to be executed upon normal program termination

func - function to be called at exit targs - optional arguments to pass to func kargs - optional keyword arguments to pass to func