Builders That Execute Python Functions

SCons User Guide 0.98.0
Prev | Chapter 17. Writing Your Own Builders | Next

# 17.4. Builders That Execute Python Functions

In SCons, you don't have to call an external command to build a file. You can, instead, define a Python function that a `Builder` object can invoke to build your target file (or files). Such a `builder function` definition looks like:

           def build_function(target, source, env):
               # Code to build "target" from "source"
               return None

The arguments of a `builder function` are:

target

  A list of Node objects representing the target or targets to be built by this builder function. The file names of these target(s) may be extracted using the Python `str` function.

source

  A list of Node objects representing the sources to be used by this builder function to build the targets. The file names of these source(s) may be extracted using the Python `str` function.

env

  The `construction environment` used for building the target(s). The builder function may use any of the environment's construction variables in any way to affect how it builds the targets.

The builder function must return a `0` or `None` value if the target(s) are built successfully. The builder function may raise an exception or return any non-zero value to indicate that the build is unsuccessful,

Once you've defined the Python function that will build your target file, defining a `Builder` object for it is as simple as specifying the name of the function, instead of an external command, as the `Builder`'s `action` argument:

           def build_function(target, source, env):
               # Code to build "target" from "source"
               return None
           bld = Builder(action = build_function,
                         suffix = '.foo',
                         src_suffix = '.input')
           env = Environment(BUILDERS = {'Foo' : bld})
           env.Foo('file')

And notice that the output changes slightly, reflecting the fact that a Python function, not an external command, is now called to build the target file:

          % scons -Q
          build_function(["file.foo"], ["file.input"])

Prev | Home | Next
Letting SCons Handle The File Suffixes | Up | Builders That Create Actions Using a `Generator`