SCons.Builder

Package SCons :: Module Builder |
[hide private]
[frames] | no frames]

# Module Builder

source code

    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.

Classes | [hide private]
| _Null
| _null
| DictCmdGenerator This is a callable class that can be used as a command generator function.
| CallableSelector A callable dictionary that will, in turn, call the value it finds if it can.
| DictEmitter A callable dictionary that maps file suffixes to emitters.
| ListEmitter A callable list of emitters that calls each in sequence, returning the result.
| OverrideWarner A class for warning about keyword arguments that we use as overrides in a Builder call.
| EmitterProxy This is a callable class that can act as a Builder emitter.
| BuilderBase Base class for Builders, objects that create output nodes (files) from input nodes (files).
| CompositeBuilder 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.

Functions | [hide private]
Builder(**kw) A factory for builder objects. | source code
_node_errors(builder, env, tlist, slist) Validate that the lists of target and source nodes are legal for this builder and environment. | source code

Variables | [hide private]
| __revision__ = ``'``src/engine/SCons/Builder.py 2725 2008/03/31 12``...``
| misleading_keywords = ``{``'``sources``'``:` `'``source``'``,` `'``targets``'``:` `'``target``'``}``

Function Details | [hide private]

### _node_errors(builder, env, tlist, slist) | source code
Validate that the lists of target and source nodes are legal for this builder and environment. Raise errors or issue warnings as appropriate.

Variables Details | [hide private]

  ### __revision__ Value:
      'src/engine/SCons/Builder.py 2725 2008/03/31 12:52:02 knight'