Builders That Create Actions Using a Generator

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

# 17.5. Builders That Create Actions Using a `Generator`

SCons Builder objects can create an action "on the fly" by using a function called a `generator`. This provides a great deal of flexibility to construct just the right list of commands to build your target. A `generator` looks like:

           def generate_actions(source, target, env, for_signature):
               return 'foobuild < %s > %s' % (target[0], source[0])

The arguments of a `generator` are:

source

  A list of Node objects representing the sources to be built by the command or other action generated by this function. The file names of these source(s) may be extracted using the Python `str` function.

target

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

env

  The `construction environment` used for building the target(s). The generator may use any of the environment's construction variables in any way to determine what command or other action to return.

for_signature

  A flag that specifies whether the generator is being called to contribute to a build signature, as opposed to actually executing the command.

The `generator` must return a command string or other action that will be used to build the specified target(s) from the specified source(s).

Once you've defined a `generator`, you create a `Builder` to use it by specifying the generator keyword argument instead of `action`.

           def generate_actions(source, target, env, for_signature):
               return 'foobuild < %s > %s' % (source[0], target[0])
           bld = Builder(generator = generate_actions,
                         suffix = '.foo',
                         src_suffix = '.input')
           env = Environment(BUILDERS = {'Foo' : bld})
           env.Foo('file')

          % scons -Q
          foobuild < file.input > file.foo

Note that it's illegal to specify both an `action` and a `generator` for a `Builder`.

Prev | Home | Next
Builders That Execute Python Functions | Up | Builders That Modify the Target or Source Lists Using an `Emitter`