SCons package

Contents

SCons package#

Module contents#

Subpackages#

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)[source]#

A factory for action objects.

class SCons.Action.ActionBase[source]#

Bases: ABC

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.

_abc_impl = <_abc._abc_data object>#
batch_key(env, target, source)#
genstring(target, source, env, executor: Executor | None = None) str[source]#
get_contents(target, source, env)[source]#
abstract get_implicit_deps(target, source, env, executor: Executor | None = None)[source]#
abstract get_presig(target, source, env, executor: Executor | None = None)[source]#
get_targets(env, executor: Executor | None)[source]#

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

get_varlist(target, source, env, executor: Executor | None = None)[source]#
no_batch_key(env, target, source)[source]#
presub_lines(env)[source]#
class SCons.Action.ActionCaller(parent, args, kw)[source]#

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)[source]#
strfunction(target, source, env)[source]#
subst(s, target, source, env)[source]#
subst_args(target, source, env)[source]#
subst_kw(target, source, env)[source]#
class SCons.Action.ActionFactory(actfunc, strfunc, convert=<function ActionFactory.<lambda>>)[source]#

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)[source]#

Bases: _ActionAction

Class for command-execution actions.

_abc_impl = <_abc._abc_data object>#
_get_implicit_deps_heavyweight(target, source, env, executor: Executor | None, icd_int)[source]#

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: Executor | None)[source]#

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: Executor | None = None)[source]#

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: Executor | None = None) str#
get_contents(target, source, env)#
get_implicit_deps(target, source, env, executor: Executor | None = None)[source]#

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

get_presig(target, source, env, executor: Executor | None = None)[source]#

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: Executor | None)#

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

get_varlist(target, source, env, executor: Executor | None = None)#
no_batch_key(env, target, source)#
presub_lines(env)#
print_cmd_line(s, target, source, env) None#

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, overrides: dict | None = None) Tuple[List, bool, bool][source]#
strfunction(target, source, env, executor: Executor | None = None, overrides: dict | None = None) str[source]#
class SCons.Action.CommandGeneratorAction(generator, kw)[source]#

Bases: ActionBase

Class for command-generator actions.

_abc_impl = <_abc._abc_data object>#
_generate(target, source, env, for_signature, executor: Executor | None = None)[source]#
batch_key(env, target, source)[source]#
genstring(target, source, env, executor: Executor | None = None) str[source]#
get_contents(target, source, env)#
get_implicit_deps(target, source, env, executor: Executor | None = None)[source]#
get_presig(target, source, env, executor: Executor | None = None)[source]#

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: Executor | None)[source]#

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

get_varlist(target, source, env, executor: Executor | None = None)[source]#
no_batch_key(env, target, source)#
presub_lines(env)#
class SCons.Action.FunctionAction(execfunction, kw)[source]#

Bases: _ActionAction

Class for Python function actions.

_abc_impl = <_abc._abc_data object>#
batch_key(env, target, source)#
execute(target, source, env, executor: Executor | None = None)[source]#
function_name()[source]#
genstring(target, source, env, executor: Executor | None = None) str#
get_contents(target, source, env)#
get_implicit_deps(target, source, env, executor: Executor | None = None)[source]#
get_presig(target, source, env, executor: Executor | None = None)[source]#

Return the signature contents of this callable action.

get_targets(env, executor: Executor | None)#

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

get_varlist(target, source, env, executor: Executor | None = None)#
no_batch_key(env, target, source)#
presub_lines(env)#
print_cmd_line(s, target, source, env) None#

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: Executor | None = None)[source]#
class SCons.Action.LazyAction(var, kw)[source]#

Bases: CommandGeneratorAction, 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.

_abc_impl = <_abc._abc_data object>#
_generate(target, source, env, for_signature, executor: Executor | None = None)[source]#
_generate_cache(env)[source]#
_get_implicit_deps_heavyweight(target, source, env, executor: Executor | None, 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: Executor | None)#

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: Executor | None = 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: Executor | None = None) str#
get_contents(target, source, env)#
get_implicit_deps(target, source, env, executor: Executor | None = None)[source]#

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

get_parent_class(env)[source]#
get_presig(target, source, env, executor: Executor | None = None)[source]#

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: Executor | None)#

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

get_varlist(target, source, env, executor: Executor | None = None)[source]#
no_batch_key(env, target, source)#
presub_lines(env)#
print_cmd_line(s, target, source, env) None#

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, overrides: dict | None = None) Tuple[List, bool, bool]#
strfunction(target, source, env, executor: Executor | None = None, overrides: dict | None = None) str#
class SCons.Action.ListAction(actionlist)[source]#

Bases: ActionBase

Class for lists of other actions.

_abc_impl = <_abc._abc_data object>#
batch_key(env, target, source)#
genstring(target, source, env, executor: Executor | None = None) str[source]#
get_contents(target, source, env)#
get_implicit_deps(target, source, env, executor: Executor | None = None)[source]#
get_presig(target, source, env, executor: Executor | None = None)[source]#

Return the signature contents of this action list.

Simple concatenation of the signatures of the elements.

get_targets(env, executor: Executor | None)#

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

get_varlist(target, source, env, executor: Executor | None = None)[source]#
no_batch_key(env, target, source)#
presub_lines(env)[source]#
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: str = '$TARGETS', **kw)[source]#

Bases: ActionBase

Base class for actions that create output objects.

_abc_impl = <_abc._abc_data object>#
batch_key(env, target, source)#
genstring(target, source, env, executor: Executor | None = None) str#
get_contents(target, source, env)#
get_implicit_deps(target, source, env, executor: Executor | None = None)[source]#
get_presig(target, source, env, executor: Executor | None = None)[source]#
get_targets(env, executor: Executor | None)#

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

get_varlist(target, source, env, executor: Executor | None = None)#
no_batch_key(env, target, source)#
presub_lines(env)#
print_cmd_line(s, target, source, env) None[source]#

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)[source]#

Joins two actions together.

Mainly, it handles ListActions by concatenating into a single ListAction.

SCons.Action._callable_contents(obj) bytearray[source]#

Return the signature contents of a callable Python object.

SCons.Action._code_contents(code, docstring=None) bytearray[source]#

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:

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)[source]#

The internal implementation for the Action factory method.

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)[source]#

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) ListAction[source]#

A factory for list actions.

Convert the input list act into Actions and then wrap them in a ListAction. If act has only a single member, return that member, not a ListAction. This is intended to allow a contained list to specify a command action without being processed into a list action.

SCons.Action._function_contents(func) bytearray[source]#

Return the signature contents of a function.

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.

class SCons.Action._null[source]#

Bases: object

SCons.Action._object_contents(obj) bytearray[source]#

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)[source]#

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)[source]#

Returns a resolved execution environment.

First get the execution environment. Then if SHELL_ENV_GENERATORS is set and is iterable, call each function to allow it to alter the created execution environment, passing each the returned execution environment from the previous call.

New in version 4.4.

SCons.Action._string_from_cmd_list(cmd_list)[source]#

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

SCons.Action._subproc(scons_env, cmd, error='ignore', **kw)[source]#

Wrapper for subprocess.Popen 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.

Deprecated since version 4.6.

SCons.Action.default_exitstatfunc(s)[source]#
SCons.Action.get_default_ENV(env)[source]#

Returns an execution environment.

If there is one in env, just use it, else return the Default Environment, insantiated if necessary.

A fiddlin’ little function that has an import SCons.Environment which cannot 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)[source]#
SCons.Action.scons_subproc_run(scons_env, *args, **kwargs) CompletedProcess[source]#

Run an external command using an SCons execution environment.

SCons normally runs external build commands using subprocess, but does not harvest any output from such commands. This function is a thin wrapper around subprocess.run() allowing running a command in an SCons context (i.e. uses an “execution environment” rather than the user’s existing environment), and provides the ability to return any output in a subprocess.CompletedProcess instance (this must be selected by setting stdout and/or stderr to PIPE, or setting capture_output=True - see Keyword Arguments). Typical use case is to run a tool’s “version” option to find out the installed version.

If supplied, the env keyword argument provides an execution environment to process into appropriate form before it is supplied to subprocess; if omitted, scons_env is used to derive a suitable default. The other keyword arguments are passed through, except that the SCons legacy error keyword is remapped to the subprocess check keyword; if both are omitted check=False will be passed. The caller is responsible for setting up the desired arguments for subprocess.run().

This function retains the legacy behavior of returning something