SCons.Tool package

Module contents

SCons tool subsystem.

Tool specification modules are callable objects that modify construction environments to dynamically enable specific types of builds. This module provides the support for handling tool modules:

• a Tool class to locate and load a tool module.

• lists of default tools for supported platform types and a mechanism to select the available ones for the current platform.

• various rules for name remapping, special-cased toolchains, etc.

• utility functions for creating common Builders (eliminating duplication when multiple tool modules could potentially create a Builder).

• create Scanners for common types used by the Builder utilities.

This is not set up like a traditional Python package: this file implements the part that other subsystems can import and call. The remaining files are either dynamically loaded tool modules that present entry points (exists() and generate()) called through the Tool instance, or support files/common logic that can be imported by those tool modules. Neither are expected to be directly imported by any other SCons subsystem (test code may reach in and do so).

Tool modules are simply callable objects that modify a construction environment. You can define custom tool specifications in any callable without needing to integrate with this subsystem.

SCons.Tool.CreateJarBuilder(env)

The Jar builder expects a list of class files which it can package into a jar file.

The jar tool provides an interface for passing other types of java files such as .java, directories or swig interfaces and will build them to class files in which it can package into the jar.

SCons.Tool.CreateJavaClassDirBuilder(env)

SCons.Tool.CreateJavaClassFileBuilder(env)

SCons.Tool.CreateJavaFileBuilder(env)

SCons.Tool.CreateJavaHBuilder(env)

SCons.Tool.FindAllTools(tools, env)

SCons.Tool.FindTool(tools, env)

SCons.Tool.Initializers(env) → None

class SCons.Tool.Tool(name, toolpath=None, **kwargs)

Bases: object

A class for loading and applying tool modules.

name is looked up using standard paths plus any specified toolpath. To avoid duplicate creation of instances, recognize if name is actually an existing instance, if so, just return ourselves without further setup.

Changed in version 4.11.0: Accept an existing instance at creation time and don’t duplicate it.

__eq__(other) → bool

Compare a Tool by name.

A Tool is equal to another Tool with the same name, and to a string matching its name (so a Tool can be used interchangeably with its name in membership tests and sets). Comparison against any other type is deferred (returns NotImplemented).

_tool_module()

Try to load a tool module.

This will hunt in the toolpath for both a Python file (toolname.py) and a Python module (toolname directory), then try the regular import machinery, then fallback to try a zipfile.

class SCons.Tool.ToolInitializer(env, tools, names)

Bases: object

A class for delayed initialization of Tools modules.

Instances of this class associate a list of Tool modules with a list of Builder method names that will be added by those Tool modules. As part of instantiating this object for a particular construction environment, we also add the appropriate ToolInitializerMethod objects for the various Builder methods that we want to use to delay Tool searches until necessary.

apply_tools(env) → None

Searches the list of associated Tool modules for one that exists, and applies that to the construction environment.

remove_methods(env) → None

Removes the methods that were added by the tool initialization so we no longer copy and re-bind them when the construction environment gets cloned.

class SCons.Tool.ToolInitializerMethod(name, initializer)

Bases: object

This is added to a construction environment in place of a method(s) normally called for a Builder (env.Object, env.StaticObject, etc.). When called, it has its associated ToolInitializer object search the specified list of tools and apply the first one that exists to the construction environment. It then calls whatever builder was (presumably) added to the construction environment in place of this particular instance.

__call__(env, *args, **kw)

get_builder(env)

Returns the appropriate real Builder for this method name after having the associated ToolInitializer object apply the appropriate Tool module.

SCons.Tool.createCFileBuilders(env)

This is a utility function that creates the CFile/CXXFile Builders in an Environment if they are not there already.

If they are there already, we return the existing ones.

This is a separate function because soooo many Tools use this functionality.

The return is a 2-tuple of (CFile, CXXFile)

SCons.Tool.createLoadableModuleBuilder(env, loadable_module_suffix: str = '$_LDMODULESUFFIX')

This is a utility function that creates the LoadableModule Builder in an Environment if it is not there already.

If it is already there, we return the existing one.

Parameters:

loadable_module_suffix – The suffix specified for the loadable module builder

SCons.Tool.createObjBuilders(env)

This is a utility function that creates the StaticObject and SharedObject Builders in an Environment if they are not there already.

If they are there already, we return the existing ones.

This is a separate function because soooo many Tools use this functionality.

The return is a 2-tuple of (StaticObject, SharedObject)

SCons.Tool.createProgBuilder(env)

This is a utility function that creates the Program Builder in an Environment if it is not there already.

If it is already there, we return the existing one.

SCons.Tool.createSharedLibBuilder(env, shlib_suffix: str = '$_SHLIBSUFFIX')

This is a utility function that creates the SharedLibrary Builder in an Environment if it is not there already.

If it is already there, we return the existing one.

Parameters:

shlib_suffix – The suffix specified for the shared library builder

SCons.Tool.createStaticLibBuilder(env)

This is a utility function that creates the StaticLibrary Builder in an Environment if it is not there already.

If it is already there, we return the existing one.

SCons.Tool.find_program_path(env, key_program, default_paths=None, add_path: bool = False) → str | None

Find the location of a tool using various means.

Mainly for windows where tools aren’t all installed in /usr/bin, etc.

Parameters:

• env – Current Construction Environment.

• key_program – Tool to locate.

• default_paths – List of additional paths this tool might be found in.

• add_path – If true, add path found if it was from default_paths.

SCons.Tool.tool_list(platform, env)